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

最后修改: 2022年 4月 11日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

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

2.绪论

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来添加新文章的细节。

@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:

我们将使用Article类作为这些API的数据传输对象（DTO）。现在，让我们在Article类中添加一些字段。

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:

我们可以在http://localhost:8080/swagger-ui/#/articles-controller访问Swagger用户界面。让我们运行该应用程序，看看上述两个API的默认行为。

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中，我们接受用户的所有详细信息，即id、title和numOfWords。在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.

一个让我们眼前一亮的选择是创建一个单独的DTO，并在其中隐藏所需的字段。如果我们想为DTO添加额外的逻辑，这种方法会很有帮助。如果适合我们的整体要求，我们可以选择使用这个选项。

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

在这篇文章中，让我们使用不同的注释来隐藏Swagger UI中的字段。

3. Using @JsonIgnore

3.使用@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.

@JsonIgnore是一个标准的Jackson注释。我们可以使用它来指定一个字段在序列化和反序列化过程中被Jackson所忽略。我们可以只对要忽略的字段添加注解，并且它将隐藏指定字段的getters和setters。

Let’s give it a try:

让我们试一试吧。

@JsonIgnore
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.

我们可以看到，现在，id字段没有显示在API描述中。Swagger也提供了注解来实现类似的行为。

4. Using @ApiModelProperty

4.使用@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:

让我们对id字段进行尝试。

@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字段在GET和POST 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.

Swagger也提供了一个替代属性，readOnly，。我们可以用它来在更新操作中隐藏指定字段，但在检索操作中仍然显示它。

Let’s examine it:

让我们研究一下。

@ApiModelProperty(readOnly = true)
private int id;

Let’s check the updated Swagger UI now:

现在让我们检查一下更新后的Swagger用户界面。

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.

从1.5.19版本开始，这个属性被标记为废弃的。对于更高的版本，让我们来探索其他注释。

5. Using @JsonProperty

5.使用@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:

Jackson提供了@JsonProperty注解。我们可以用它来添加与POJO字段的getters/setters相关的元数据，这些元数据可以在对象的序列化/反序列化期间使用。我们可以设置注解的access属性，只允许对一个特定的字段进行读操作。

@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

6.使用@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.

@ApiParam也是一个Swagger注解，我们可以用它来指定与请求参数有关的元数据。我们可以将hidden属性设置为true，以便隐藏任何属性。不过，我们在这里有一个限制。只有当我们使用@ModelAttribute而不是@RequestBody来访问请求数据时，它才能发挥作用。

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:

让我们研究一下这种情况下的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

7.结语

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.

源代码可在GitHub上获得，。