Spring Boot excels as a framework that makes it convenient to expose a set of REST based services. But once an application is developed, it is so trivial to create a new resource or modify a method signature that it becomes difficult to keep the documentation up-to-date so that clients can properly consume the REST API.
The OpenAPI specification (originally Swagger) helps automate the generation of documentation by examining your Controller classes and documenting the purpose, parameters, and expected output of each endpoint method.
Below is an example of the OpenAPI documentation created for a simple UserController.java REST service.
Clicking into the GET method of ‘/api/user’, you can even execute the call and view the results directly from this page. For convenience, it also provides the equivalent curl command.
Spring Boot prerequisites
If you are reading this article, I’m assuming you already have a Spring Boot web app with @RestController. If you do not have one, you can use my project code from the article building a Docker image from a Spring Boot jar.
The abbreviated instructions are that you need to install:
- OpenJDK 11+
- Docker CE
Then build the Spring Boot web app.
git clone https://github.com/fabianlee/spring-boot-with-docker-push.git cd spring-boot-with-docker-push # compile and build REST service ./gradlew bootJar
Adding OpenAPI/Swagger dependency
Now that you have a Spring Boot REST service, you need to add the ‘springdoc-openapi-ui’ dependency to your build. This will automatically make the OpenAPI documentation available at ‘http://localhost:8080/swagger-ui/index.html’
If you are using gradle, then add it to build.gradle
dependencies {
...
implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'
}
Or pom.xml if using Maven.
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.9</version> </dependency>
Validate OpenAPI documentation page
Rebuild and run your application again.
./gradlew bootJar bootRun
Now point your browser at http://localhost:8080/swagger-ui/index.html and you should see that your REST based services are listed similar to below.
Tailoring documenting using annotations
If you want to add detail to the out-of-the-box experience of OpenAPI documentation, you need to add annotations to your class and methods that can provide the extra level of detail expected by consumers of the API.
For example, adding the following annotation to the GET method of UserController.java provides the easy to read description shown in the screenshot above.
@Operation(summary = "get list of users")
Another example is adding expected response information to the method. The GET method of UserController.java is simple and always returns success 200. But we could add parameters to this annotation for content media type, schemas, and multiple response codes as described here.
@ApiResponse(responseCode = "200")
Configuring OpenAPI
You can set general options for the OpenAPI generation in application.properties.
For example, if you do not want the documentation page showing your @Controller exposed at ‘/info‘, you can add the following property.
springdoc.pathsToExclude=/info
If you want to specify the services to include based on package name
springdoc.packagesToScan=com.package1, com.package2
If you want to specify the set of services to include based on path
springdoc.pathsToMatch=/v1, /api/balance/**
Here is a listing of the other properties that can be used for configuration.
REFERENCES
swagger.io – home of OpenAPI specification
balendung.com, documenting methods using OpenAPI
dzone John Thompson, spring boot and swagger2
howtodoinjava, using swagger2 annotations to create detailed docs
springdoc.org, properties that can be set in application.properties to configure OpenAPI
MISC REFERENCES
geeksforgeeks.org – example of spring boot and thymeleaf
baeldung.com – using request parameters with spring thymeleaf
baeldung.com – spring boot quick start with examples for CRUD, REST, and thymeleaf
dzone Dan Newton, logback with spring boot
baeldung.com, spring boot logging
Leo Gutierrez, Writing custom endpoints in Spring Actuator, Endpoint with ReadOperation
codebjoe.de, using maven and git sources for actuator info as well as custom class
javadevjournal.com, custom health endpoint and controller endpoint
masterspringboot.com, adding scrape_config for prometheus for actuator
zetcode.com, the 3 days that responses can be written with Spring Boot
github RAJNISH3, example of ThymeleafConfiguration
github krizsan, example of ThymeleafConfiguration
bezdoker.com, full example spring JPA and REST with CrossOrigin annotation
stackoverflow, multiple ways of doing REST versioning with path mapping
lisenet.com, AlertManager with slack alerts
elatov.github.io, shows how to create scrapeconfig that reads annotations ‘prometheus.io/scrape’