Spring Microservices RESTFul API Documentation With Swagger Part 1
This article explains, how Spring boot Micro-services can be documented using Swagger2
Join the DZone community and get the full member experience.Join For Free
When back-end APIs are developed and exposed to the client, having good documentation is key. API documentation should be properly structured so that it provides all information related to the API. Without having proper documentation, the client using the API will struggle to access it. If this happens, the API is useless. There are several tools to document the APIs/RESTful Services. However, when you have developed a RESTful service using Spring Boot, then Swagger2 is the obvious choice for documentation because it makes your documentation very easy.
- Swagger is the oldest and most mature spec.
- Supports most languages.
- Easy to get started with.
- Good community support.
- Has a Maven plugin and is easily configurable with a Spring Boot application.
In this and subsequent articles, we will see how can Swagger2 be configured with a Spring Boot RESTful service. In Part 1, I will show you how to configure your application without security and in Part 2, we'll add security.
Configuration Without Security
The following steps need to be performed to include Swagger in your Spring Boot application and document the API. I will do it for a fresh project
Step 1 — Create the Project Structure and create artifacts in the correct location.
Step 2 — Add the following Swagger dependencies in your pom.xml file.
Step 3 — Configuring Swagger in the application. To configure Swagger in the application, we need to create a config file, which will have all Swagger related configurations. I will explain each after this code snippet.
In above code snippet, you can see following configuration needs to be done:
@EnableSwagger2- Annotation enables Swagger in the Support in the Class
select()- method invocation on Docket bean instance that returns an
APISelectBuilderobject, which provides the
api()method and paths methods that need to be configured.
api()- method filters the Controllers and methods that need to be documented. You can see I am setting the
Filter. So, all classes that are annotated with
RestControllerwill be filtered.
Path()- method acts as an additional filter to generate documentation only for the path starting with some specific String. In my case, we are allowing all options.
Now, you can see there are few customizations that I had done like:
- Providing Produce and consume types. Here, I had configured two, "application/json" and "application/xml".
ApiInfo- We can set API Details for providing more details to the consumer, like setting name, emailId, terms and conditions, license etc.
SecuritySchema- Will see in the next article (Swagger with Security)
SecurityContext- Will see in the next article (Swagger with Security)
globalResponseMessage- We can set global Response messages as well for handling errors like 500 and 404, and that will be applicable for all APIs that are being documented
There are a few more customization that can be performed on top of the
Step 4 - Once Swagger Configurations are done, Controllers and Model objects need to be documented using available annotations.
1. Annotations of End Points
Any Class having the
@RestController annotation will be considered as REST API Controllers (Resource).
In this Controller/Resource, you can see many annotations. Let's go one by one and see what they are responsible for:
@RestController- It is a combination of
@ResponseBody, and it suggests that this class will be considered as a REST API Controller that will accept all API call requests.
@RequestMapping- Class-level annotation that maps requests to items to controller. The method-level
@RequestMappingannotations map web requests to the handler methods of the controller.
@DeleteMapping- To handle different requests coming from the client.
@API- Class-level annotation to describe the API, and you can use this tag to explain the functionality of API.
@ApiOperation- Method-level annotation that describes the end point and its response type. You can also override the default response messages of HTTP methods. You can use the
@ApiResponseannotation to document other responses, in addition to the regular HTTP 200 OK, like this.
Service Class Implementation
Spring Boot application
2. Annotations for Models
@ApiModelProperty can be used to document the Models used in the application.
@ApiModel- Class-level annotation that helps to describe the Model. It has two main fields value and a description.
@ApiModelProperty- Field-level annotation that helps to describe the Field in detail. It has many properties; I am highlighting important ones you can use:
- name - Unique Name
- value - Detail of field
- datatype - string, decimal, float, int etc
- readOnly - true/false
- example - Sample Value
Step 5 - Once endpoint and Model documentation are done, start the Spring Boot application and access the following URL: http://localhost:8080/swagger-ui.html.
Once you access this url, Swager main page will get open which will have all your apis listed which you have documented
In this page, you can see following things:
- Your Controller/Resource Customized name.
- All end points which was annotated by
@ApiOperationand then you can see the description provided by you at right.
- API Info provided in Swagger config file.
When you access POST Method of Items for creating Item:
In this screenshot you can see following
- Response Content Type - Set in Swagger Config. You can chose either XML or JSON.
- Example Value - Picked from Model, documented by you.
- Try Out - There will be a Try Out button. Once you click on it, a request will go to the server and perform the required operation:
Swagger Documentation for Item Model
Other than API Documentation, Swagger can also be used for defining your API Specs, and then later, you can perform API Validation as well. As it is integrated with your application, you can easily access the services.
I hope this is helpful. In the next article (Part 2), I will show you Swagger Configurations for adding security, so that only valid users can access Swagger documentation.
Opinions expressed by DZone contributors are their own.