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 {
}