Document Spring REST API 101

Today, I will discuss one of the most essential parts of developing the REST API; Documentation.

Why do we need to document API?

The first and foremost reason to document API is to help user to understand your API. The user who will use your API is not the one who writes the API. And the document will need to answer the most frequent questions potentially from the users, which are what is available and how to use them. Lastly, the document will tell you where you made the changes in your API as well.

Adding Swagger and Springfox

The OpenAPI specification defines the industry-standard specification for designing REST APIs to understand the capabilities of the service without access to source code or asking developers. https://swagger.io/specification/

Spring Boot Swagger 3 Maven dependency

– For Spring Boot 3:
To use Swagger 3 in your Maven project, you need to add the springdoc-openapi-starter-webmvc-ui dependency to your project’s pom.xml file:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.0.3</version>
</dependency>

Spring Boot Swagger Gradle dependency

– For Spring Boot 3:
To use Swagger 3 in your Gradle project, you need to add the springdoc-openapi-starter-webmvc-ui dependency to your project’s build.gradle file: