What is Swagger?
Swagger, now known as OpenAPI Specification, is a tool that provides a set of rules and conventions for building, interacting with, and documenting APIs (application-programmable interfaces). It provides a standard to describe the robust APIs, which makes it easier for developers to understand the capabilities of a service without accessing its source code or documentation directly.
Why do we need to document the APIs?
Let’s first understand why we even need to document our APIs. Say we have developed a Spring Boot application and have our endpoints ready to be used. We asked our frontend developer to integrate our endpoint with the UI. The frontend developer may need the answer to the following question:
- What are the API endpoints available?
- What is the payload structure that needs to hit the endpoint?
- What is the response body they may aspect?
- What is the method type for the requesting API endpoint?
The easiest solution to the above problem is to write down API documentation along with all the information and hand it to the required developers. But there is a problem with this approach: if the APIs get updated, then we have to update our document too and make sure that it is always in sync with the APIs, which is always a continuous and consistent process and increases the workload for the developers.
How Swagger Works?
Swagger/OpenAPI Specification automatically creates the documents based on the metadata we have in our RESTFul APIs. We add the Swagger metadata to our code and it informs Swagger about:
- Which are the APIs?
- Which parameters are they going to use?
- What they are used for, and so on.
Swagger can infer a lot of information, such as metadata, method signatures, etc., from our code. Still, if we want, we can provide extra metadata like API descriptions, notes, etc., of which we want consumers to be aware. After we are done with all the metadata we need to add to our APIs, Swagger will generate documents in various formats, from JSON to fully readable HTML. The reason why this is awesome is because, say, if the APIs get updated, the developers need to only update the metadata for the changed APIs, and the document will get updated automatically. This means that as long as we are generating the document with each build, we do not need to worry about updating the document; it will get updated itself.
Add Swagger in Spring Boot
In order to add Swagger to the Spring Boot, we need to follow the following steps:
- Generating Swagger 2 Spring dependency
- Enable Swagger in Spring Boot
- Configuring Swagger
- Adding details as annotations to APIs
Steps to add OpenAPI Specification to Spring Boot
We can use the following methods to document the Spring Boot APIs:
- Using Springfox Swagger2
- Using Springfox Swagger UI
For this tutorial, we will be using the following Spring Boot project: TaskManager Services. In order to learn how to create this service, please refer to CRUD Operations with Spring Boot and MonogDB.
Documenting APIs using Springfox Swagger2
Step 1- Add dependency: Springfox Swagger2
First of all, we need to add the Swagger dependency to our Spring Boot project. For this, we will be using the following dependency:
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>Step 2- Enable Swagger in Spring Boot
After this, we are required to enable Swagger in our Spring Boot project. For this, we move to the main class of our Spring Boot application and add the @EnableSwagger2 annotation.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Adding @EnableSwagger2 annotation to the Main class in Spring Boot
*
* @author paulsofts
*/
@SpringBootApplication
@EnableSwagger2
public class TaskmanagerApplication {
public static void main(String[] args) {
SpringApplication.run(TaskmanagerApplication.class, args);
}
}Make sure to change the Spring Boot version to 2.X.X in the pom.xml file and add the following properties in the application.properties file.
spring.mvc.pathmatch.matching-strategy = ANT_PATH_MATCHERStep 3- Testing Swagger URL
Now, Swagger will automatically generate the API documentation for our APIs. We use the following http://localhost:9090/v2/api-docs default Swagger URL for localhost to see the JSON-format API documentation.
