Hide a Request Field in Swagger API – 在Swagger API中隐藏一个请求字段

最后修改: 2022年 4月 11日

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.

我们可以使用Swagger UI作为一个平台,以方便的方式对API接口进行可视化和互动。它是一个强大的工具,可以用最少的配置要求生成API结构。

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.

在本文中,我们将重点讨论如何使用Swagger与Spring Boot REST APIs。具体而言,我们将探讨在Swagger UI中隐藏请求字段的不同方法。

2. Introduction


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

为了简单起见,我们将创建一个基本的Spring Boot应用程序,并使用Swagger UI探索API。

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.

让我们使用Spring Boot创建一个简单的ArticleApplication。我们使用ArticleController暴露了两个API。使用GET API,我们要接收所有文章的相关细节。

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

另一方面,我们使用POST API来添加新文章的细节。

public class ArticlesController {

    private ArticleService articleService;

    public List<Article> getAllArticles() {
        return articleService.getAllArticles();

    public void addArticle(@RequestBody Article 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:


Img1 e1648650028181
Img2 e1648650100457



















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.

POST API中,我们接受用户的所有详细信息,即idtitlenumOfWords。在GETAPI中,我们在响应中返回同样的字段。我们可以看到,在默认情况下,两个API的所有字段都由Swagger显示。

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.

现在,假设我们想使用一个单独的后端逻辑来设置id字段。在这种情况下,我们不希望用户输入与id字段相关的信息。为了避免任何混淆,我们想在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.

在这篇文章中,让我们使用不同的注释来隐藏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:


private int id;

Let’s rerun the application and examine the Swagger UI:Img4 Img 3

让我们重新运行应用程序并检查Swagger UI:Img4Img 3

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.

@ApiModelProperty 提供了与模型对象的属性相关的元数据。我们可以使用注解的hidden属性来隐藏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.

在上述情景中,我们发现id字段在GETPOST API中都是隐藏的。假设我们想让用户查看id详细信息,作为GET API响应的一部分。在这种情况下,我们需要寻找其他选项。

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:


Img5 Img6

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.

我们可以看到,现在id字段对于GET API是可见的,但对于POST API来说仍然是隐藏的–它支持只读操作。

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.

通过这种方式,我们能够为POST API模型定义隐藏id字段,但仍能在GET API响应中显示它。

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:


public void addArticle(@ModelAttribute Article article) {

@ApiParam(hidden = true)
private int id;

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

让我们研究一下这种情况下的Swagger UI规范。

Img8 Img7


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

我们成功地在POST API请求数据定义中隐藏了id字段。

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.

我们已经探索了不同的选项来修改Swagger UI中模型对象属性的可见性。所讨论的注解也提供了其他一些功能,我们可以用它们来更新Swagger规范。我们应该根据我们的要求使用适当的方法。

The source code is available over on GitHub.