API Documentation - THM-ATLAS/spring-backend GitHub Wiki

Integration

Integration with Gradle dependencies in build.gradle.kts

dependencies {
    ...
    implementation("org.springdoc:springdoc-openapi-ui:1.5.9")
    ...
}

The API documentation is now built automatically.

Call

Specify paths in src/main/resources/application.properties

springdoc.swagger-ui.path=/api/docs
springdoc.api-docs.path=/api/docs/raw

Then it can be called under e.g. localhost:8080/api/docs. our docs can be called under http://atlas.mni.thm.de/api/docs

Expand and edit

The API documentation can be extended and edited In the RestConrollers .

API Responses

With the annotation @ApiResponses we extend the responses with status codes and descriptions.

import io.swagger.v3.oas.annotations.media.Content
import io.swagger.v3.oas.annotations.media.Schema
import io.swagger.v3.oas.annotations.responses.ApiResponse
import io.swagger.v3.oas.annotations.responses.ApiResponses

@ApiResponses(
            value = [
                ApiResponse(responseCode = "200", description = "OK - Returns ...."),
                ApiResponse(responseCode = "404", description = "...NotFoundException", content = [Content(schema = Schema(hidden = true))]),
            ])

With content = [Content(schema = schema(hidden = true)) we specify that no schema of the returned data type needs to be provided in the documentation.

Parameters

We use the @Parameter annotation to edit the parameters in the documentation.
We use this to hide the AuthenticationPrincipal with @Parameter(hidden = true ), which is automatically sent with each request and therefore does not need to be included in the documentation.

import io.swagger.v3.oas.annotations.Parameter

fun doSomething(@Parameter(hidden = true ) @AuthenticationPrincipal user: AtlasUser): someType {

}