Java Automation Job Top
We’re looking for a Backend Java/Spring Developer with Integration Experience: Read More

1. Overview

We can use Swagger UI as a platform to visualize and interact with API interfaces in a convenient manner. It's a powerful tool to generate API structures with minimal configuration required.

In this article, we'll focus on using Swagger with Spring Boot REST APIs. Specifically, we'll explore different ways to hide a request field in Swagger UI.

2. Introduction

For the sake of simplicity, we'll create a basic Spring Boot application and explore the APIs using Swagger UI.

Let’s create a simple ArticleApplication using Spring Boot. We’re exposing two APIs using ArticlesController. Using the GET API, we want to receive details related to all the articles.

On the other hand, we use POST API to add details for a new article:

@RestController
@RequestMapping("/articles")
public class ArticlesController {

    @Autowired
    private ArticleService articleService;

    @GetMapping("")
    public List<Article> getAllArticles() {
        return articleService.getAllArticles();
    }

    @PostMapping("")
    public void addArticle(@RequestBody Article article) {
        articleService.addArticle(article);
    }

}

We'll be using the Article class as a Data Transfer Object (DTO) for these APIs. Now, let’s add a few fields in the Article class:

public class Article {

    private int id;
    private String title;
    private int numOfWords;
    
    // standard getters and setters

}

We can access the Swagger UI at http://localhost:8080/swagger-ui/#/articles-controller. Let’s run the application and see the default behavior for the above two APIs:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

In the POST API, we’re accepting all the details – namely, id, title, and numOfWords – from a user. In the GET API, we're returning the same fields in the response. We can see that by default, all the fields are shown by Swagger for both APIs.

Now, suppose we want to use a separate back-end logic to set the id field. In such a scenario, we don’t want the user to enter information related to the id field. To avoid any confusion, we want to hide this field in Swagger UI.

An immediate option that strikes our mind is creating a separate DTO and hiding the required fields in it. This method can be helpful if we want to add additional logic for DTOs. We can choose to use this option if it suits our overall requirements.

For this article, let’s use different annotations to hide fields in Swagger UI.

3. Using @JsonIgnore

@JsonIgnore is a standard Jackson annotation. We can use it to specify that a field is to be ignored by Jackson during serialization and deserialization. We can add the annotation to just the field to be ignored, and it’ll hide both getters and setters for the specified field.

Let’s give it a try:

@JsonIgnore
private int id;

Let’s rerun the application and examine the Swagger UI:

We can see that now, the id field is not shown in the API descriptions. Swagger also provides annotations to achieve similar behavior.

4. Using @ApiModelProperty

@ApiModelProperty provides metadata related to the properties of the model object. We can use the hidden property of the annotation to hide a field in the definition of a model object in Swagger UI.

Let's try it for the id field:

@ApiModelProperty(hidden = true)
private int id;

In the above scenarios, we find that the id field is hidden for both GET and POST APIs. Suppose we want to allow users to view id details as part of GET API response. In this case, we need to look for other options.

Swagger provides an alternative property, readOnly, as well. We can use it to hide the specified field during update operations but still show it for retrieval operations.

Let’s examine it:

@ApiModelProperty(readOnly = true)
private int id;

Let’s check the updated Swagger UI now:

We can see that the id field is visible for the GET API now but remains hidden for the POST API – it supports Read-Only operations.

This property is marked as deprecated as of version 1.5.19. For higher versions, let’s explore other annotations.

5. Using @JsonProperty

Jackson provides the @JsonProperty annotation. We can use it to add metadata related to getters/setters of a POJO field that can be used during serialization/deserialzation of objects. We can set the access property of the annotation to allow only read operations on a particular field:

@JsonProperty(access = JsonProperty.Access.READ_ONLY)
private int id;

In this manner, we’re able to hide the id field for the POST API model definition but can still show it in the GET API response.
Let’s explore another way to achieve the desired functionality.

6. Using @ApiParam

@ApiParam is also a Swagger annotation that we can use to specify metadata related to request parameters. We can set the hidden property to true in order to hide any property. Though, we have a limitation here: It works only if we're using @ModelAttribute instead of @RequestBody to access request data.

Let's try it out:

@PostMapping("")
public void addArticle(@ModelAttribute Article article) {
    articleService.addArticle(article);
}

@ApiParam(hidden = true)
private int id;

Let's examine the Swagger UI specifications for this case:

 

We're successfully able to hide the id field in the POST API request data definition.

7. Conclusion

We've explored different options to modify the visibility of model object properties in Swagger UI. The discussed annotations offer several other features as well, which we can use to update the Swagger specifications. We should use the appropriate methods as per our requirements.

The source code is available over on GitHub.

REST bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course :

>> CHECK OUT THE COURSE
REST footer banner
Comments are closed on this article!