Setting up Swagger document for a Spring project
Swagger document is a widely used conventional documentation used to exchange REST apis information. Many developers write the full document, known as swagger specs using some tool or manually. However, The best documentation is the one that is very close to the code.
Some of the popular open-source libraries that can help to generate these documents are Open API and Swagger UI.
In this article, we will be using spring doc open api for generating swagger documents.
Let’s start
1) Add dependencies
If (you are using spring web flux project) {
then add below dependencies
If ( gradle ){
add below line in build.gradle file :
implementation("org.springdoc:springdoc-openapi-webflux-ui:1.4.3")
} else if (maven) {
add below dependency
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-ui</artifactId>
<version>1.4.3</version>
</dependency>
} else if (you are using spring boot application){
then add below dependencies
If ( gradle ){
add below line in build.gradle file :
implementation("org.springdoc:springdoc-openapi-ui:1.4.3")
} else if (maven) {
add below dependency
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.4.3</version>
</dependency>
}
2) Setting properties.
open application.yaml / application<env>.yaml file and add paths to swagger file.
springdoc:
api-docs:
path: /api-docs
swagger-ui:
path: /swagger-ui.html
3) Let’s see the details.
Now open the url : http://localhost:8080/swagger-ui.html
4 Let’s configure it
a) Remove unwanted APIs : Sometime, we may have a health check or other rest APIs which we don’t want to show in specs
We can remove them by adding below the property
springdoc: paths-to-exclude: /health, /monitoring
b) Title : In the main startup class, add this annotation,
@OpenAPIDefinition(info = Info(title = "Swagger APIs", version = "1.0", description = "Documentation of APIs v1.0"))
c) Add annotation to the function
For Kotlin, we can refer to this annotation,
@Operation(summary = "Get Person Details")
@ApiResponses(value = [
ApiResponse(responseCode = "200", description = "Person ", content = [
(Content(mediaType = "application/json",
schema = Schema(implementation = Person::class)
))]),
ApiResponse(responseCode = "400", description = "Bad request", content = [Content()]),
ApiResponse(responseCode = "404", description = "Did not find any Person ", content = [Content()])]
)
@GetMapping(value = ["Person"],
produces = [MediaType.APPLICATION_JSON_VALUE])
fun getPerson(@RequestHeader(value = "userId") id: String): Mono<Person>? {}
or
@Operation(summary = "Get Person Details")
@ApiResponses(value = [
ApiResponse(responseCode = "200", description = "Found Persons", content = [
(Content(mediaType = "application/json", array = (
ArraySchema(schema = Schema(implementation = Persons::class)))))]),
ApiResponse(responseCode = "400", description = "Bad request", content = [Content()]),
ApiResponse(responseCode = "404", description = "Did not find any Person ", content = [Content()])]
)
For Java,
@Operation(summary = "details of api")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Found Person",
content = { @Content(mediaType = "application/json",
schema = @Schema(implementation = Person.class)) }),
@ApiResponse(responseCode = "400", description = "Invalid id supplied",
content = @Content),
@ApiResponse(responseCode = "404", description = "Person not found",
content = @Content) })