Enhancing Swagger Documentation with Custom Annotations
In the previous section, we have learned about API documentation. We saw a high-level overview structure of the Swagger documentation. In this section, we will customize the Swagger element info. Swagger annotations are defined in the swagger-annotations-1.5.20.jar file.
Step 1: Open the SwaggerConfig.java.
Step 2: Create a constant DEFAULT_API_INFO of type ApiInfo.
Step 3: Hold the ctrl key and click on the constant type (ApiInfo). The ApiInfo class will open.
Step 4: Copy the two constants DEFAULT _CONTACT and DEFAULT from the class. or copy the following code and paste it in the SwaggerConfig.java. Rename the constant DEFAULT to DEFAULT_API_INFO.
Step 5: Configure the contact details of the developer or organization.
Step 6: Configure DEFAULT_API_INFO. In this configuration, provide all the information which we want to show in the Swagger documentation.
Step 7: Restart the application.
Step 8: Open the browser and type the URI http://localhost:8080/v2/api-docs. It shows the updated contact detail and API info in the documentation.
Accepting and producing XML format
We should be more specific about what we produce and what we consume. So, in the next step, we will add content negotiation. We can accept input in application/json or application/xml and produce response in application/json or application/xml format.
Let's specify the content negotiation in our project.
Step 1: In the SwaggerConfig.java, goto the Docket api() and add .produces(DEFAULT_PRODUCES_AND_CONSUMES).consumes(DEFAULT_PRODUCES_AND_CONSUMES).
Step 2: Create a constant DEFAULT_PRODUCES_AND_CONSUMES.
Step 3: Create a HashSet and add two values application/json and application/xml.
Note that we cannot directly pass the values to the HashSet. So we have passed a List to the constructor of HashSet.
Step 4: Open the browser and type the URI http://localhost:8080/v2/api-docs.
The above image shows that it consume and produces JSON and XML format.
We can add more description about user model such as date of birth must be in the past, the name must have at least five characters, etc. Let's add more description in the User model.
Step 1: Open the User.java and add @ApiModel annotation just above the class name. Add the description about the User model.
@ApiModel: It provides additional information about Swagger Models.
We have added the following description:
Step 2: Add another annotation @ApiModelProperty just above the dob variable.
@ApiModelProperty: It allows controlling swagger-specific definitions such as values, and additional notes.
Step 3: Similarly, add @ApiModelProperty annotation for the name variable.
Step 4: Restart the application.
Step 5: Open the browser and type the URI http://localhost:8080/v2/api-docs. If we look at the description of the User model, the description which we have specified appears here.
The API documentation is much important as API. The consumer of our service should not have any question about how to consume service, what are the different details, how the output looks like, etc. Everything should be clear to the consumer so that the user can understand easily.
Hence, the Swagger documentation is beneficial for the consumer of service. Swagger provides a lot of annotations that can be used to enhance model, operations, and swagger configurations.