springdoc-openapi

One very important aspect of developing APIs, for example, RESTful services, is how to document them so that they are easy to use. The Swagger specification from SmartBear Software is one of the most widely used ways of documenting RESTful services. Many leading API gateways have native support for exposing the documentation of RESTful services using the Swagger specification.

In 2015, SmartBear Software donated the Swagger specification to the Linux Foundation under the OpenAPI Initiative and created the OpenAPI Specification. The name Swagger is still used for the tooling provided by SmartBear Software.

springdoc-openapi is an open source project, separate from the Spring Framework, that can create OpenAPI-based API documentation at runtime. It does so by examining the application, for example, inspecting WebFlux and Swagger-based annotations.

We will look at full source code examples in upcoming chapters, but for now, the following condensed screenshot (removed parts are marked with “…”) of a sample API documentation will do:

Figure 2.1: Sample API documentation visualized using Swagger UI

Note the big Execute button, which can be used to actually try out the API, not just read its documentation!

springdoc-openapi helps us to document the APIs exposed by our microservices. Now, let’s move on to Spring Data.