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.

public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());

Step 5: Configure the contact details of the developer or organization.

public static final Contact DEFAULT_CONTACT = new Contact("Andrew", "http://www.javatpoint.com", "demo@javatpoint.com");

Step 6: Configure DEFAULT_API_INFO. In this configuration, provide all the information which we want to show in the Swagger documentation.

public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("RESTful API Demo", "Api Documentation Demo", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());

SwaggerConfig.java

package com.javatpoint.server.main;
import java.util.ArrayList;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//Configuration
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig 
{
//configuring the contact detail
public static final Contact DEFAULT_CONTACT = new Contact("Andrew", "http://www.javatpoint.com", "javatpoint");
//configuring DEFAULT_API_INFO
public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("RESTful API Demo", "Api Documentation Demo", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
//creating bean
@Bean
public Docket api()
{
ApiInfo apiInfo;
return new Docket(DocumentationType.SWAGGER_2).apiInfo(DEFAULT_API_INFO);
}
}

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.

Enhancing Swagger Documentation with Custom Annotations

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).

return new Docket(DocumentationType.SWAGGER_2).apiInfo(DEFAULT_API_INFO).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.

private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES = new HashSet<String>(Array.asList("application/json","appication/xml"));

SwaggerConfig.java

package com.javatpoint.server.main;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//Configuration
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig 
{
//configuring the contact detail
public static final Contact DEFAULT_CONTACT = new Contact("Andrew", "http://www.javatpoint.com", "javatpoint");
//configuring DEFAULT_API_INFO
public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("RESTful API Demo", "Api Documentation Demo", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
//two format which we want to produce and consume
private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES = new HashSet<String>(Arrays.asList("application/json","appication/xml"));
//creating bean
@Bean
public Docket api()
{
ApiInfo apiInfo;
return new Docket(DocumentationType.SWAGGER_2).apiInfo(DEFAULT_API_INFO).produces(DEFAULT_PRODUCES_AND_CONSUMES).consumes(DEFAULT_PRODUCES_AND_CONSUMES);
}
}

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.

User.java

package com.javatpoint.server.main.user;
import java.util.Date;
import javax.validation.constraints.Past;
import javax.validation.constraints.Size;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(description="All details about the user")
public class User 
{
private Integer id;
@Size(min=5, message="Name should have atleast 5 characters")
@ApiModelProperty(notes="name should have atleast 5 characters")
private String name;
@Past
@ApiModelProperty(notes="Birth date should be in the past")
private Date dob;
//default constructor	
protected User()
{
	
}
public User(Integer id, String name, Date dob) 
{
super();
this.id = id;
this.name = name;
this.dob = dob;
}
public Integer getId() 
{
return id;
}
public void setId(Integer id) 
{
this.id = id;
}
public String getName() 
{
return name;
}
public void setName(String name) 
{
this.name = name;
}
public Date getDob() 
{
return dob;
}
public void setDob(Date dob) 
{
this.dob = dob;
}
@Override
public String toString() 
{
//return "User [id=" + id + ", name=" + name + ", dob=" + dob + "]";
return String.format("User [id=%s, name=%s, dob=%s]", id, name, dob);
}
}

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.

Click here to download Enhancing Swagger Doucmentation with Custom Annotations project

Next TopicMonitoring APIs with Spring Boot Actuator

← prev next →