Adding Open API Swagger support to Spring Boot

Pagination and Sorting using Spring Data JPA

Documenting API is very important so that users of the API can get a sense of how to call the API and know about different parameters, data types supported, etc. This article deeps dive into exposing REST API that supports Open API Documentation.

Introduction

API users need to understand how to interact with the API. OpenAPI Specification (OAS) defines a standard interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the API. Swagger implements this interface and in this article, we will walk through changes required to be done to a Spring Boot REST application.

Spring Boot Rest Application

We will use an existing spring boot rest application and will add support for the swagger documentation. This application has few Resources already exposed as RESTFul API,  like
BlogControllerV0,
BlogControllerV1,
BlogControllerV2 etc.

pom.xml changes
Just include the springdoc-openapi-ui dependency and do mvn install
pom.xml changes
<!--  swagger ui -->
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-ui</artifactId>
	<version>1.5.10</version>
</dependency>

Accessing the Swagger documentations

Swagger documentation can be accessed by following URL
http://localhost:8080/swagger-ui/index.html
It will show a page like bellow





If we want to access the JSON data containing the swagger documentation by visiting following URL
http://localhost:8080/v3/api-docs
{
   "openapi":"3.0.1",
   "info":{
      "title":"OpenAPI definition",
      "version":"v0"
   },
   "servers":[
      {
         "url":"http://localhost:8080",
         "description":"Generated server url"
      }
   ],
   "paths":{
      "/blogapi/v2/blogs":{
         "get":{
            "tags":[
               "blog-controller-v-2"
            ],
            "operationId":"getBlogStories",
            "responses":{
               "200":{
                  "description":"OK",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"array",
                           "items":{
                              "$ref":"#/components/schemas/BlogStory"
                           }
                        }
                     }
                  }
               }
            }
         },
         "post":{
            "tags":[
               "blog-controller-v-2"
            ],
            "operationId":"addBlogStory",
            "requestBody":{
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/BlogStory"
                     }
                  }
               },
               "required":true
            },
            "responses":{
               "200":{
                  "description":"OK",
                  "content":{
                     "application/json":{
                        "schema":{
                           "$ref":"#/components/schemas/BlogStory"
                        }
                     }
                  }
               }
            }
         }
      },
      "/blogapi/v1/categories":{
         "get":{
            "tags":[
               "category-controller"
            ],
            "operationId":"getBlogCats",
            "responses":{
               "200":{
                  "description":"OK",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"array",
                           "items":{
                              "$ref":"#/components/schemas/BlogCategory"
                           }
                        }
                     }
                  }
               }
            }
         },
         "post":{
            "tags":[
               "category-controller"
            ],
            "operationId":"addCats",
            "requestBody":{
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/BlogCategory"
                     }
                  }
               },
               "required":true
            },
            "responses":{
               "200":{
                  "description":"OK",
                  "content":{
                     "application/json":{
                        "schema":{
                           "$ref":"#/components/schemas/BlogCategory"
                        }
                     }
                  }
               }
            }
         }
      },
      "/blogapi/v2/blogs/{id}":{
         "get":{
            "tags":[
               "blog-controller-v-2"
            ],
            "operationId":"getBlogStory",
            "parameters":[
               {
                  "name":"id",
                  "in":"path",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "responses":{
               "200":{
                  "description":"OK",
                  "content":{
                     "application/json":{
                        "schema":{
                           "$ref":"#/components/schemas/BlogStory"
                        }
                     }
                  }
               }
            }
         }
      }
   },
   "components":{
      "schemas":{
         "BlogStory":{
            "type":"object",
            "properties":{
               "id":{
                  "type":"string"
               },
               "name":{
                  "type":"string"
               },
               "summary":{
                  "type":"string"
               },
               "description":{
                  "type":"string"
               },
               "category":{
                  "type":"string"
               }
            }
         },
         "BlogCategory":{
            "type":"object",
            "properties":{
               "id":{
                  "type":"string"
               },
               "name":{
                  "type":"string"
               }
            }
         }
      }
   }
}

Summary

In this article, we saw how to quickly add support for Swagger documentation in the Spring boot APP. With very few changes we can get working and interactive swagger API documentation. The Swagger implementation can also be used to customize the report.

References

No comments :

Post a Comment

Please leave your message queries or suggetions.