隱藏 Swagger API 請求字段

1. 概述

我們可以使用 Swagger UI 作為平台，以方便的方式可視化並與 API 接口進行交互。它是一個功能強大的工具，可以生成 API 結構，所需的配置極少。

在本文中，我們將重點介紹使用 Swagger 與 Spring Boot REST API 的使用。具體來説，我們將探索在 Swagger UI 中隱藏請求字段的不同方法。

2. 簡介

為了簡化起見，我們將創建一個基本的 Spring Boot 應用程序，並使用 Swagger UI 探索 API。

我們將使用 Spring Boot 創建一個簡單的 ArticleApplication。我們使用 ArticlesController 暴露了兩個 API。我們想使用 GET API 接收有關所有文章的詳細信息。

另一方面，我們使用 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);
    }

}

我們將使用 Article 類作為這些 API 的數據傳輸對象 (DTO)。現在，讓我們在 Article 類中添加一些字段：

public class Article { private int id; private String title; private int numOfWords; // standard getters and setters }

我們可以訪問 Swagger UI：http://localhost:9090/springbootapp/swagger-ui/index.html#/articles-controller。讓我們運行應用程序並查看上述兩個 API 的默認行為：

在 POST API 中，我們接受用户輸入的所有詳細信息，包括 id、title 和 numOfWords。在 GET API 中，我們返回相同字段的響應。我們可以看到，默認情況下，Swagger 顯示了這兩個 API 的所有字段。

現在，假設我們想使用單獨的後端邏輯來設置 id 字段。在這種情況下，我們不希望用户輸入與 id 字段相關的信息。為了避免混淆，我們希望在 Swagger UI 中隱藏此字段。

我們腦海中浮現的一個 immediate 選項是創建單獨的 DTO 並隱藏必需字段。如果我們想為 DTO 添加額外的邏輯，這種方法會很有幫助。如果這種方法符合我們的總體要求，我們可以選擇使用它。

對於本文檔，讓我們使用不同的註解來在 Swagger UI 中隱藏字段。

3. 使用

是標準的 Jackson 註解。我們可以使用它來。我們可以將註解添加到要忽略的字段上，並且 @JsonIgnore private int id;
讓我們重新運行應用程序並檢查 Swagger UI:

我們可以看到， 字段未出現在 API 描述中。Swagger 還提供註解來實現類似的行為。

4. 使用 @Schema

@Schema 註解可用於定義 OpenAPI 規範中一組元素的 Schema，或定義 Schema 的附加屬性。它適用於例如參數、Schema 類（也稱為“模型”）、這些模型的屬性、請求和響應內容以及標頭。我們可以使用 隱藏屬性 來隱藏模型對象的定義中的字段在 Swagger UI 中的。

讓我們嘗試將其應用於 id 字段：

@Schema(hidden = true) private int id;

在上述場景中，我們發現 id 字段在 GET 和 POST API 中都已隱藏。如果我們想允許用户查看 id 字段作為 GET API 響應的一部分，則需要尋找其他選項。
Swagger 提供另一個屬性 readOnly 屬性。我們可以使用它來在更新操作期間隱藏指定的字段，但仍顯示它用於檢索操作。但是，readOnly 屬性已棄用並已通過 accessMode 屬性替換：

讓我們檢查一下：

@Schema(accessMode = AccessMode.READ_ONLY) private int id;

讓我們檢查一下更新後的 Swagger UI：

我們可以看到 id 字段現在在 GET API 中可見，但在 POST API 中仍然隱藏——它支持 Read-Only 操作。

5. 使用

Jackson 提供註解。我們可以使用它來添加與 POJO 字段的 getter/setter 元數據，這些元數據可用於對象的序列化/反序列化過程中。我們可以通過設置屬性來允許特定字段僅進行 操作：

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

通過這種方式，我們可以隱藏字段對於 API 模型定義的顯示，但仍然可以在 API 響應中顯示它。
讓我們探索另一種實現所需功能的方法。

6. 使用 >

Jackson 還提供了 標註，我們可以使用它來對類的字段進行視圖限制，並且相同的限制也將適用於 Swagger UI。

讓我們創建一個 Views 類並創建兩個視圖 – 公有和私有：

public class Views { public static class Public {} public static class Private {} }

接下來，讓我們創建一個新的 Author 類，並將其應用限制：

public class Author { @JsonView(Views.Private.class) private Integer id; @JsonView(Views.Public.class) private String name; @JsonView(Views.Public.class) private int email; // standard getters and setters }

在這裏，我們已註釋了字段 – name 和 email 為 @JsonView(Views.Public.class) ，以便僅包含這些字段在公共視圖中。

接下來，讓我們將公共視圖應用於我們的 GET 方法，以便僅在 Swagger UI 中顯示 name 和 email：

@JsonView(Views.Public.class) @GetMapping public List<Author> getAllAuthors() { return authorService.getAllAuthors(); }

讓我們現在檢查 Swagger UI：

正如我們所看到的，僅顯示 email 和 name 字段在 Swagger UI 中。

對於 POST 請求，我們也可以使用 @JsonView，但它只能與 @RequestBody 結合使用，並且不支持 @ModelAttribute。

讓我們查看一個 POST 請求的示例：

@PostMapping public void addAuthor(@RequestBody @JsonView(Views.Public.class) Author author) { authorService.addAuthor(author); }

讓我們現在檢查更新後的 Swagger UI：

我們可以看到，id 字段在 API 描述中不可見，並且僅 email 和 name 可用於編輯。

讓我們探索另一種實現所需功能的途徑。

7. 使用 @Hidden

@Hidden 也是一個 Swagger 註解，用於標記指定的資源、類或 Bean 類型為隱藏。

讓我們來試試看:

@Hidden private int id;

讓我們來審視一下 Swagger UI 的規範：

我們成功地在 GET & POST API 請求的數據定義中隱藏了 id 字段。

7. 結論

我們探討了在 Swagger UI 中修改模型對象屬性可見性的不同選項。討論的註解也提供了一些其他功能，我們可以利用它們來更新 Swagger 規範。我們應根據我們的要求使用適當的方法。