swagger openapi

Set up Swagger document for Spring project

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

swagger openapi

 

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

 

 

Leave a Comment

Your email address will not be published. Required fields are marked *