Documenting Spring Boot Rest API With OpenAPI 3.0

How To Document Spring Boot Micro Service Using Spring Doc OpenAPI

Overview

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 Properties

For more properties option, please refer to spring doc.

Step 4 : Run Your Application By Executing Below Command On Terminal:

mvn spring-boot:run

Step 5: Access Below URLs To Test :

Step 6 : By Click http://localhost:8080/microservice-ui you will get below Screen :

http://localhost:8080/swagger-ui/index.html?configUrl=/microservice-docs/swagger-config

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

Execution Response

Step 8 : Click ‘Schemas’ to view request payload

Inbound Payload

Conclusion

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.

I am a Software Developer living in Pretoria, South Africa. I have over 8 years’ experience working in tech as a professional software engineer.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store