added docs

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 120
+
+[*.{kt,kts}]
+ktlint_code_style = android
+ktlint_version = 0.48.2
+ij_kotlin_imports_layout=*

.github/pull_request_template.md

@@ -5,7 +5,7 @@ Closes #[issue number]
 [Description of the changes proposed in the pull request]
 
 # Review checklist
--   [ ] Properly documents API changes in `docs/openapi.yml`
+-   [ ] Properly documents API changes in the corresponding controller test
 -   [ ] Contains enough appropriate tests
 -   [ ] Behavior is as expected
 -   [ ] Clean, well structured code

.github/workflows/ci.yml

@@ -6,7 +6,7 @@ on:
       - master
       - develop
   pull_request:
-    branches: 
+    branches:
       - master
       - develop
 
@@ -42,6 +42,7 @@ jobs:
         with:
           name: lint-reports
           path: build/reports/ktlint
+        if: always()
 
   test:
     name: 'Test'
@@ -75,3 +76,57 @@ jobs:
           path: |
             build/reports/tests/test
             build/reports/jacoco/test
+        if: always()
+
+
+  docs:
+    name: 'Docs'
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    env:
+      NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+      NETLIFY_SITE_ID: ${{ vars.NETLIFY_SITE_ID }}
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v3
+
+      - name: Setup Java
+        uses: actions/setup-java@v3
+        with:
+          java-version: ${{ env.JAVA_VERSION }}
+          distribution: ${{ env.JAVA_DISTRIBUTION }}
+
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@v2
+        with:
+          gradle-version: ${{ env.GRADLE_VERSION }}
+
+      - name: Generate documentation
+        run: ./gradlew generateDocs
+
+      - name: Generate redoc file
+        run: npx redoc-cli build docs/openapi3.json -o docs/index.html
+
+      - name: Deploy to netlify (main)
+        if: github.ref == 'refs/heads/main'
+        run: |
+          npx netlify-cli deploy --dir=docs --prod
+
+      - name: Deploy to netlify (develop)
+        if: github.ref == 'refs/heads/develop'
+        run: |
+          npx netlify-cli deploy --dir=docs --alias develop
+
+      - name: Deploy to netlify (preview)
+        if: github.event_name == 'pull_request'
+        run: |
+          npx netlify-cli deploy --json --dir=docs > deployment_data
+          echo 'deploy_url='$(grep -oP '(?<="deploy_url": ")[^"]*' deployment_data) >> $GITHUB_ENV
+
+      - uses: mshick/add-pr-comment@v2
+        with:
+          message: |
+            Check the documentation preview: ${{ env.deploy_url }}
+          allow-repeats: true

.gitignore

@@ -1,9 +1,12 @@
 HELP.md
+
+src/main/resources/application-dev.properties
 .gradle
 build/
 !gradle/wrapper/gradle-wrapper.jar
 !**/src/main/**/build/
 !**/src/test/**/build/
+docs/
 
 ### STS ###
 .apt_generated

README.md

@@ -1,5 +1,5 @@
-# Website NIAEFEUP - BackEnd  
-[![codecov](https://codecov.io/gh/NIAEFEUP/website-niaefeup-backend/branch/develop/graph/badge.svg?token=4OPGXYESGP)](https://codecov.io/gh/NIAEFEUP/website-niaefeup-backend)  
+# Website NIAEFEUP - BackEnd
+[![codecov](https://codecov.io/gh/NIAEFEUP/website-niaefeup-backend/branch/develop/graph/badge.svg?token=4OPGXYESGP)](https://codecov.io/gh/NIAEFEUP/website-niaefeup-backend)
 The online platform for NIAEFEUP.
 
 ## Development setup
@@ -21,7 +21,7 @@ For automatic restart to fire up every time a source file changes, make sure tha
 Run the following command in your shell:
 
 ```bash
-gradle bootRun
+./gradlew bootRun
 ```
 
 ### Linting
@@ -35,21 +35,27 @@ Although IntelliJ does not provide linting suggestions for Kotlin out of the box
 You can fire up the analysis yourself by running in your shell:
 
 ```bash
-gradle ktlintCheck
+./gradlew ktlintCheck
+```
+
+You can fix the lint automatically by running in your shell:
+
+```bash
+./gradlew ktlintFormat
 ```
 
 #### With a git hook
 
 You can setup a local precommit [git hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) for lint analysis running a Gradle task provided by the used linting plugin:
 
 ```bash
-gradle addKtlintCheckGitPreCommitHook
+./gradlew addKtlintCheckGitPreCommitHook
 ```
 
 Or even an auto-format hook, if that is your thing:
 
 ```bash
-gradle addKtlintFormatGitPreCommitHook
+./gradlew addKtlintFormatGitPreCommitHook
 ```
 
 ### Testing
@@ -63,9 +69,31 @@ Run the test suite as usual, selecting the respective task for running.
 Run the following command in your shell:
 
 ```bash
-gradle test
+./gradlew test
+```
+
+
+### API Documentation
+API documentation is generated through the use of the [Spring REST Docs API specification Integration (aka restdocs-api-spec)](https://github.com/ePages-de/restdocs-api-spec), a [Spring Rest Docs](https://spring.io/projects/spring-restdocs) extension that builds an [OpenAPI specification](https://www.openapis.org/) or a [Postman collection](https://learning.postman.com/docs/sending-requests/intro-to-collections/) from its description, included in the controller tests. To see examples of how to document the API, hop to one of the controller tests and read the [API documentation wiki page](https://github.com/NIAEFEUP/website-niaefeup-backend/wiki/API-documentation).
+
+Find the current version of the API documentation [here](https://develop--niaefeup-backend-docs.netlify.app/).
+
+The Postman collection is also available [here](https://develop--niaefeup-backend-docs.netlify.app/postman-collection.json).
+
+##### With IntelliJ
+Run the `generateDocs` gradle task to generate the OpenAPI specification or the Postman collection.
+
+##### With the command line
+Run the following command in your shell:
+
+```bash
+./gradlew generateDocs
 ```
 
+###### Results
+Find the OpenAPI specification and Postman collection under `docs/` after running the task.
+
+
 ## Project Details
 
 ### Project Structure

build.gradle.kts

@@ -1,12 +1,16 @@
+import org.gradle.api.tasks.testing.logging.TestExceptionFormat
+import org.gradle.api.tasks.testing.logging.TestLogEvent
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
     id("org.springframework.boot") version "3.0.0"
     id("io.spring.dependency-management") version "1.1.0"
-    kotlin("jvm") version "1.7.21"
-    kotlin("plugin.spring") version "1.7.21"
-    kotlin("plugin.jpa") version "1.7.21"
-    id("org.jlleitschuh.gradle.ktlint") version "11.0.0"
+    kotlin("jvm") version "1.8.10"
+    kotlin("plugin.spring") version "1.8.10"
+    kotlin("plugin.jpa") version "1.8.10"
+    id("org.jlleitschuh.gradle.ktlint") version "11.2.0"
+    id("com.epages.restdocs-api-spec") version "0.17.1"
+
     jacoco
 }
 
@@ -29,11 +33,21 @@ dependencies {
     implementation("org.jetbrains.kotlin:kotlin-reflect")
     implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
     implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")
+    implementation("ch.qos.logback:logback-core:1.4.5")
+    implementation("org.slf4j:slf4j-api:2.0.6")
+    implementation("com.cloudinary:cloudinary:1.0.14")
     annotationProcessor("org.springframework.boot:spring-boot-configuration-processor")
     implementation("org.springframework.boot:spring-boot-starter-validation:3.0.0")
     developmentOnly("org.springframework.boot:spring-boot-devtools")
     runtimeOnly("com.h2database:h2")
     testImplementation("org.springframework.boot:spring-boot-starter-test")
+    testImplementation("ch.qos.logback:logback-classic:1.4.5")
+    testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc:3.0.0")
+    testImplementation("com.epages:restdocs-api-spec-mockmvc:0.17.1")
+    testImplementation("org.springframework.boot:spring-boot-starter-test") {
+        exclude(group = "org.mockito2", module = "mockito-core")
+    }
+    testImplementation("org.mockito:mockito-inline:5.0.0")
 }
 
 tasks.withType<KotlinCompile> {
@@ -45,6 +59,29 @@ tasks.withType<KotlinCompile> {
 
 tasks.withType<Test> {
     useJUnitPlatform()
+    testLogging {
+        events = mutableSetOf(
+            TestLogEvent.FAILED,
+            TestLogEvent.SKIPPED
+        )
+        exceptionFormat = TestExceptionFormat.FULL
+        showExceptions = true
+        showCauses = true
+        showStackTraces = true
+
+        debug {
+            events = mutableSetOf(
+                TestLogEvent.FAILED,
+                TestLogEvent.PASSED,
+                TestLogEvent.SKIPPED,
+                TestLogEvent.STANDARD_OUT,
+                TestLogEvent.STANDARD_ERROR
+            )
+            exceptionFormat = TestExceptionFormat.FULL
+        }
+        info.events = debug.events
+        info.exceptionFormat = debug.exceptionFormat
+    }
 }
 
 tasks.test {
@@ -59,3 +96,61 @@ tasks.jacocoTestReport {
         html.required.set(true)
     }
 }
+
+// Rest Docs API Spec tasks configuration
+val apiSpecTitle = "NIAEFEUP Website - Backend API specification"
+val apiSpecDescription =
+    """This specification documents the available endpoints and possible operations on the website's backend.
+        |For each of the operations, its purpose, security, requests and possible responses are documented.
+        |
+        |Postman collection also available <a href="postman-collection.json" download>here</a>.
+    """.trimMargin()
+
+configure<com.epages.restdocs.apispec.gradle.OpenApi3Extension> {
+    setServer("http://localhost:8080")
+    title = apiSpecTitle
+    description = apiSpecDescription
+    version = "${project.version}"
+    format = "json"
+    tagDescriptionsPropertiesFile =
+        "src/test/kotlin/pt/up/fe/ni/website/backend/utils/documentation/tag-descriptions.yaml"
+}
+
+configure<com.epages.restdocs.apispec.gradle.PostmanExtension> {
+    title = apiSpecTitle
+    version = "${project.version}"
+    baseUrl = "https://localhost:8080"
+}
+
+tasks.register<Copy>("generateDocs") {
+    dependsOn(tasks.named("openapi3"))
+    dependsOn(tasks.named("postman"))
+    dependsOn(tasks.named("fixExamples"))
+
+    from("${project.buildDir}/api-spec/openapi3.json")
+    into(File("docs"))
+
+    from("${project.buildDir}/api-spec/postman-collection.json")
+    into(File("docs"))
+}
+
+tasks.register("fixExamples") {
+    dependsOn(tasks.named("openapi3"))
+    doLast {
+        val objectMapper = com.fasterxml.jackson.databind.ObjectMapper()
+
+        val spec = objectMapper.readTree(File("${project.buildDir}/api-spec/openapi3.json"))
+        (spec as com.fasterxml.jackson.databind.node.ObjectNode)
+            .findValues("examples").forEach { examples ->
+                examples.forEach { example ->
+                    (example as com.fasterxml.jackson.databind.node.ObjectNode)
+                        .replace("value", objectMapper.readTree(example.get("value").asText()))
+                }
+            }
+
+        objectMapper.writer().withDefaultPrettyPrinter().writeValue(
+            File("${project.buildDir}/api-spec/openapi3.json"),
+            spec
+        )
+    }
+}

src/main/kotlin/pt/up/fe/ni/website/backend/BackendApplication.kt

@@ -5,9 +5,10 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
 import org.springframework.boot.runApplication
 import org.springframework.data.jpa.repository.config.EnableJpaAuditing
 import pt.up.fe.ni.website.backend.config.auth.AuthConfigProperties
+import pt.up.fe.ni.website.backend.config.upload.UploadConfigProperties
 
 @SpringBootApplication
-@EnableConfigurationProperties(AuthConfigProperties::class)
+@EnableConfigurationProperties(AuthConfigProperties::class, UploadConfigProperties::class)
 @EnableJpaAuditing
 class BackendApplication
 

src/main/kotlin/pt/up/fe/ni/website/backend/config/Logging.kt

@@ -0,0 +1,8 @@
+package pt.up.fe.ni.website.backend.config
+
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory.getLogger
+
+interface Logging {
+    val logger: Logger get() = getLogger(this::class.java)
+}

src/main/kotlin/pt/up/fe/ni/website/backend/config/auth/AuthConfig.kt

@@ -50,7 +50,9 @@ class AuthConfig(
 
     @Bean
     fun jwtEncoder(): JwtEncoder {
-        val jwt = RSAKey.Builder(authConfigProperties::publicKey.get()).privateKey(authConfigProperties::privateKey.get()).build()
+        val jwt = RSAKey.Builder(authConfigProperties::publicKey.get()).privateKey(
+            authConfigProperties::privateKey.get()
+        ).build()
         return NimbusJwtEncoder(ImmutableJWKSet(JWKSet(jwt)))
     }