Enhancing Swagger Documentation With Custom Annotations

Accepting and Producing XML format

In this step, we will add content negotiation to be more specific. We will accept input in application/XML or application/JSON and then produce the response in application/XML or application/JSON format.

Now we will see the steps for adding content negotiation to our project.

Step 1: Go to the Docket api() in SwaggerConfig.java file and add .produces(DefaultProducesAndConsumes).consumes(DefaultProducesAndConsumes)

return new Docket(DocumentationType.SWAGGER_2).apiInfo(DefaultAPI_info).produces(DefaultProducesAndConsumes).consumes(DefaultProducesAndConsumes); 

You can also try this code with Online Java Compiler

Run Code

Step 2: Create a constant with the name DefaultProducesAndConsumes.

private static final Set<String> DefaultProducesAndConsumes = null;  

You can also try this code with Online Java Compiler

Run Code

Step 3: Now create a HashSet and add two values, application/JSON and application/XML, to it. As we can not directly pass the two values to the HashSet, we are passing a List to the constructor of HashSet.

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

You can also try this code with Online Java Compiler

Run Code

Now, let’s look at the code of  SwaggerConfig.java.

package com.codingNinjas.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  
@EnableSwagger2  
public class SwaggerConfig   
{  
public static final Contact DefaultContact = new Contact("Ninja", "Ninja.com", "codingNinja");
public static final ApiInfo DefaultAPI_info = new ApiInfo("Coding Ninjas RESTful API Demo", "Coding Ninjas documentation of API demo", "1.0", "urn:tos",  DefaultContact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
private static final Set<String> DefaultProducesAndConsumes = new HashSet<String>(Arrays.asList("application/xml","application/json")); 
@Bean
public Docket api()  
{  
ApiInfo apiInfo;  
return new Docket(DocumentationType.SWAGGER_2).apiInfo(DefaultAPI_info).produces(DefaultProducesAndConsumes).consumes(DefaultProducesAndConsumes);
}
}

You can also try this code with Online Java Compiler

Run Code

Step 4: Open your browser and then type the URL http://localhost:8080/v2/api-docs.

It consumes and produces XML and JSON format, as shown in the above output.

We can add more descriptions about the user model, such as the name, which must have at least five characters, and the date of birth, which must be in the past. Let's go through the steps where we will add more description to the user model. 

Step 1: Open the User.java file, and just above the class name, add the @ApiModel annotation. And then add the description of the User model.

@ApiModel: This is used to provide additional information about the Swagger models.

@ApiModel(description="All the details of the ninja user")  

You can also try this code with Online Java Compiler

Run Code

Step 2: Now, just above the dob variable, you must add another annotation @ApiModelProperty.

@ApiModelProperty(notes="The date of birth should be in the past!")

You can also try this code with Online Java Compiler

Run Code

Step 3: Similarly, you must add the @ApiModelProperty annotation for the name variable.

@ApiModelProperty(notes="The name of the ninja should have at least five characters!")  

You can also try this code with Online Java Compiler

Run Code

Let’s look at the code of the NinjaUser.java file.

package com.codingNinja.server.main.ninjauser;  
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 the details of the ninja user")  
public class NinjaUser   
{  
private Integer id;  
@Size(min=5, message="The name of the ninja should have at least five characters")
@ApiModelProperty(notes="The name of the ninja should have at least five characters")  
private String NinjaName;  
@Past  
@ApiModelProperty(notes="The date of birth should be in the past!")
private Date DateOfBirth;    
protected NinjaUser()  
{  
      
}  
public NinjaUser(Integer id, String NinjaName, Date DateOfBirth)   
{  
super();  
this.id = id;  
this.NinjaName = NinjaName;  
this.DateOfBirth = DateOfBirth;  
}  
public Integer getId()   
{  
return id;  
}  
public void setId(Integer id)   
{  
this.id = id;  
}  
public String getNinjaName()   
{  
return NinjaName;  
}  
public void setNinjaName(String NinjaName)   
{  
this.NinjaName = NinjaName;  
}  
public Date getDob()   
{  
return DateOfBirth;  
}  
public void setDob(Date DateOfBirth)   
{  
this.DateOfBirth = DateOfBirth;  
}  
@Override  
public String toString()   
{  
return String.format("NinjaUser [id=%s, NinjaName=%s, DateOfBirth=%s]", id, NinjaName, DateOfBirth);  
}  
}  

You can also try this code with Online Java Compiler

Run Code

Step 4 - Now restart the application.

Step 5: Open your browser and type the URL http://localhost:8080/v2/api-docs. The description we specified will appear here in the description of the user model.

We hope you have understood everything about enhancing the swagger documentation with Custom Annotations.🙌🥳

Frequently Asked Questions

What is the difference between Swagger and Postman?

Swagger is an API specification used to mention the specifications of the API. In contrast, Postman is an API client used to test the API based on these specifications. 

What is the advantage of Swagger?

Swagger is a very potent tool for API developers. The foremost advantage of Swagger is that it provides a page integrated with UI. The UI contains a list of all the APIs, and developers can test the APIs directly using the UI. 

Can we use Swagger for free?

A swagger is an open-source tool that can be directly accessed from its GitHub repository. So yes, we can use swagger for free. 

What is a REST API?

REST in REST API stands for Representational State Transfer. A REST API or RESTful API is any API that adheres to the constraints set forward by a REST architecture. 

What are spring boot annotations?

It is the metadata that provides data about a program. In other words, it provides supplementary information about the program.

Conclusion

This blog covered all the important points regarding enhancing the swagger documentation using custom annotations. We also looked at an example of how to customize the swagger documentation using custom annotations. 

• Spring Boot
• Learn what rest API is in 10 minutes
• Introduction to Spring Boot
• How to Build a REST API 
• Spring Boot Version 
   

Do check out our blogs on object-oriented programming and data structures. 

Don’t stop here. Check out Coding Ninjas for more unique courses and guided paths. Also, try Coding Ninjas Studio for more exciting articles, interview experiences, and fantastic Data Structures and Algorithms problems.

Happy Learning Ninja! 🥷