Introduction to Openapi in Spring Rest

Go Back to Course Outline

I. Introduction

Prior to Spring version 2.2.0 we have Swagger2 (< v2.0) and Swagger3 (v2.0) to document our REST API in a Spring project. A good API is very helpful, especially for API client developers. And moreover, it is very important to always generate the most latest API documentation available so that everyone is in sync. This process could be tedious without the automated feature available in Swagger.

II. Swagger vs OpenAPI

OpenAPI is the specification while Swagger is one of the reference implementations. We can say that OpenAPI has become one of the legacies of Swagger. For more information, a comparison is available here https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi.

III. Documenting a Spring REST API Project with OpenAPI

1. Create a new Spring Boot Project and add the following dependencies at a minimum.
1. spring-boot-starter-actuator
2. spring-boot-starter-web
3. springdoc-openapi-ui - with this dependency, OpenAPI3 specification as well as HTML documentation are automatically generated.
2. Set the following in application.properties in case we want to override:
1. springdoc.api-docs.path, defaultValue=/v3/api-docs, overrideValue=/api-docs
2. springdoc.swagger-ui.path, defaultValue=swagger-ui.html, overrideValue=/swagger-docs
3. Note, there is no need to add a dependency springdoc-openapi-core since we already have the openapi-ui.
4. To generate the json and yaml OpenAPI description during build time, we need to add the plugin springdoc-openapi-maven-plugin, modify the configuration since we changed the default URLs. See code below.

IV. Let's Run the Application

We should be able to access the following pages:

• htp://localhost:8080/api-docs
• htp://localhost:8080/swagger-docs

V. Codes

Complete source code is available at the repository in the reference section.

References

• https://github.com/czetsuya/Spring-Keycloak-with-REST-API
• https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/
• https://springfox.github.io/springfox/docs/current/#introduction
• https://github.com/springdoc/springdoc-openapi-maven-plugin