1. 概述
我們可以使用 Swagger UI 作為平台，以方便的方式可視化並與 API 接口進行交互。它是一個強大的工具，可以生成 API 結構，且所需的配置極少。
在本文中，我們將重點介紹使用 Swagger 與 Spring Boot REST API 結合使用。具體來説，我們將探索在 Swagger UI 中隱藏請求字段的不同方法。
2. 簡介
為了簡化説明，我們將創建一個基本的 Spring Boot 應用程序，並使用 Swagger UI 探索其 API。
讓我們使用 Spring Boot 創建一個簡單的 <i >ArticleApplication</i>。 我們使用 <i >ArticlesController</i> 暴露了兩個 API。 我們希望使用 GET API 接收所有文章的詳細信息。
另一方面，我們使用 <i >POST</i> 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
}
我們可以通過 http://localhost:9090/springbootapp/swagger-ui/index.html#/articles-controller 訪問 Swagger UI。讓我們運行應用程序並查看以上兩個 API 的默認行為：
在 POST API 中，我們接受所有詳細信息，包括 id、title 和 numOfWords 等字段，這些信息來自用户。在 GET API 中，我們返回相同字段，這些字段在響應中。我們可以看到，默認情況下，Swagger 顯示了所有字段，對於這兩個 API 而言。
現在，假設我們想要使用單獨的後端邏輯來設置 id 字段。在這種情況下，我們不想讓用户輸入與 id 字段相關的信息。為了避免混淆，我們希望在 Swagger UI 中隱藏此字段。
我們腦海中浮現的 inmediato 選項是創建單獨的 DTO 並在此 DTO 中隱藏所需字段。如果我們要為 DTO 添加額外的邏輯，此方法將很有幫助。我們可以選擇使用此選項，如果它符合我們的總體要求。
對於本文檔，讓我們使用不同的註解來隱藏 Swagger UI 中的字段。
3. 使用 @JsonIgnore
@JsonIgnore 是一個標準的 Jackson 註解。我們可以使用它來 指定字段在序列化和反序列化過程中應被 Jackson 忽略。 我們可以將註解添加到要忽略的字段上，並且 它將隱藏該字段的 getter 和 setter 方法。
讓我們嘗試一下:
@JsonIgnore
private int id;
讓我們重新運行該應用程序並檢查 Swagger UI：
我們可以看到， 字段未在 API 描述中顯示。Swagger 還提供註釋來實現類似的行為。
4. 使用 @Schema 標註
@Schema 標註可用於為 OpenAPI 規範中的一組元素定義一個 Schema，或定義 Schema 的附加屬性。它適用於例如 參數、Schema 類（也稱為“模型”）、這些模型的屬性、請求和響應內容以及標頭。我們 可以使用標註的 隱藏屬性 在 Swagger UI 中隱藏模型對象的字段。
讓我們嘗試它，針對 id 字段：
@Schema(hidden = true)
private int id;在上述場景中，我們發現 字段對於 和 API 均被隱藏。如果我們要允許用户在 API 響應中查看 詳情，則需要考慮其他選項。
Swagger 提供了一個替代屬性，即 只讀。我們可以使用它來在更新操作期間隱藏指定字段，但仍顯示其詳情用於檢索操作。但是，只讀 屬性已被棄用，並被 訪問模式 屬性所取代：
讓我們來審視一下：
@Schema(accessMode = AccessMode.READ_ONLY)
private int id;讓我們現在檢查更新後的 Swagger UI：
我們可以看到，對於 id 字段現在在 GET API 中可見，但在 POST API 中仍然隱藏——它支持只讀操作。
5. 使用 @JsonProperty 註解
Jackson 提供了 <i@JsonProperty> 註解。我們可以使用它來為 POJO 字段的 getter/setter 方法添加元數據，這些元數據可用於對象的序列化/反序列化過程中。 我們可以通過設置註解的 <iaccess> 屬性，僅允許對特定字段進行 <iread> 操作：
@JsonProperty(access = JsonProperty.Access.READ_ONLY)
private int id;通過這種方式，我們可以隱藏 id 字段對於 POST API 模型定義的屬性，但仍然可以在 GET API 響應中顯示它。
讓我們探索另一種實現所需功能的途徑。
6. 使用 @JsonView
Jackson 還提供了 @JsonView註解，我們可以利用它來對類的字段進行視圖限制，並且相同的限制也將適用於 Swagger UI。
讓我們創建一個 Views 類並創建兩個視圖：Public 和 Private：
public class Views {
public static class Public {}
public static class Private {}
}
接下來，讓我們創建一個新的 作者 類，並將限制應用於該類：
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)，僅將這些字段包含在 Public 視圖中。
接下來，我們為 GET 方法應用 Public 視圖，以便在 Swagger UI 中僅顯示 name 和 email。
@JsonView(Views.Public.class)
@GetMapping
public List<Author> getAllAuthors() {
return authorService.getAllAuthors();
}讓我們現在檢查 Swagger UI：
正如我們所見，Swagger UI 中只顯示 email 和 name 字段。
對於 POST 請求，我們也可以使用 @JsonView，但它只能與 @RequestBody 結合使用，不支持 @ModelAttribute。
讓我們通過一個 POST 請求示例進行檢查：
@PostMapping
public void addAuthor(@RequestBody @JsonView(Views.Public.class) Author author) {
authorService.addAuthor(author);
}
讓我們現在檢查一下更新後的 Swagger UI：
我們可以看到，API 描述中未顯示 id 字段，並且只有 email 和 name 可用於編輯。
讓我們探索另一種實現所需功能的途徑。
7. 使用 @Hidden 標註
@Hidden 也是一個 Swagger 註解，用於標記指定的資源、類或 Bean 類型為隱藏。
我們來試試看：
@Hidden
private int id;讓我們來研究一下 Swagger UI 的規範，以解決此問題：
我們已成功地隱藏了 id 字段在 GET & POST API 請求數據定義中的內容。
7. 結論
我們探討了多種修改 Swagger UI 中模型對象屬性可見性的選項。討論的註解也提供了一些其他功能，我們可以利用它們來更新 Swagger 規範。我們應根據我們的要求選擇合適的方法。
