Documenting Spring Boot Rest API With OpenAPI 3.0
How To Document Spring Boot Micro Service Using Spring Doc OpenAPI
Overview
springdoc-openapi java library helps automating the generation of API documentation using spring boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.
Automatically generates documentation in JSON/YAML and HTML format APIs. This documentation can be completed by comments using swagger-api annotations.
The primary focus of this article is to document an existing Spring Boot REST APIs with OpenAPI 3.0.
To follow through this article, you need to have a REST Spring Boot Application. You can access the source code on Github. I recommend that you follow through the article first before accessing the source code.
Getting Started
Step 1 : Add Below Dependency To Your Existing Maven Spring Boot Project
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.3</version>
</dependency>Step 2 : Add Below Annotation To Your Main Application Class
@SpringBootApplication
@OpenAPIDefinition(info = @Info(title = "Student MicroService", description = "This is A Microservice Rest Project", version = "2.0"))
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}Step 3 : Add Below Properties To Your application.properties File
# SpringDoc
# Object Value. Description. Default Value
#String. For custom path of the OpenAPI documentation in Json format. Default Value=/v3/api-docs
springdoc.api-docs.path=/microservice-docs
#Boolean. To disable the springdoc-openapi endpoint (/v3/api-docs by default). Default Value=/true
springdoc.api-docs.enabled=true
#List of Strings.The list of paths to exclude (comma separated). Default Value=
#springdoc.paths-to-exclude=
# Packages to include
# springdoc.packagesToScan=com.package1, com.package2
# Paths to include
#springdoc.pathsToMatch=/v1, /api/balance/**
#Swagger UI Properties
# Boolean. To disable the swagger-ui endpoint (/swagger-ui.html by default). Default Value=true
springdoc.swagger-ui.enabled=true
#String, For custom path of the swagger-ui HTML documentation. Default Value=/swagger-ui.html
springdoc.swagger-ui.path=/microservice-ui
#String.To configure, the path of a custom OpenAPI file . Will be ignored if urls is used. Default Value=
#springdoc.swagger-ui.url=/index.html
# End SpringDoc And Swagger UI PropertiesFor more properties option, please refer to spring doc.
Step 4 : Run Your Application By Executing Below Command On Terminal:
mvn spring-boot:runStep 5: Access Below URLs To Test :
- Click http://localhost:8080/microservice-docs.yaml to download the yaml file that can be used in Postman And Swagger Editor.
- Click http://localhost:8080/microservice-docs to view the JSON file with swagger definitions
- Click http://localhost:8080/microservice-ui
Step 6 : By Click http://localhost:8080/microservice-ui you will get below Screen :
The below Snippet Code already added, reflects on the Swagger UI Page.
@OpenAPIDefinition(info = @Info(title = "Student MicroService", description = "This is A Microservice Rest Project", version = "2.0"))Step 7 : Execute The API From Swagger UI
Click ‘Post’ endpoint and then click ‘Try it out’ and lastly click then ‘Execute’
Step 8 : Click ‘Schemas’ to view request payload
Conclusion
We have seen how to add documentation and configuration for existing Spring Boot REST Application. This is my first medium article, I hope you enjoyed the article. The final source code can be found on Github by clicking here. I will do the video version of all my articles. You can like and subscribe here.
Remember “Knowledge increases by sharing not saving it” do share your views and comments in the comments section. Let’s help each other improve our skill set, knowledge and experience.
