作者：Ole Lensmar
最近針對 Java 的 Swagger 核心工具為 Swagger 執行階段用於為您的 API 產生 Swagger 定義的核心註解新增了許多功能。讓我們快速瀏覽一下這些功能，看看它們如何在您使用由下而上的方法建立 Swagger 定義時，協助您提供更完整的 API 中繼資料。
@SwaggerDefinition
@SwaggerDefinition 註解是核心註解中最大的新增功能；它提供您一種將定義層級的中繼資料新增至產生的 Swagger 的方法，所有這些都直接與 Swagger 2.0 規格中的 Swagger 物件屬性相關聯
- info - 提供關於整個 API 的中繼資料 (標題、描述、授權等)
- consumes - 此定義中描述的 API 所使用的全域 MIME 類型清單
- produces - 此定義中描述的 API 所產生的全域 MIME 類型清單
- schemes - 此 API 支援的傳輸協定
- basePath - 覆寫 Swagger 執行階段推斷的 basePath
- host - 覆寫 Swagger 執行階段推斷的 host
- tags - 規格中使用的標籤清單，包含其他中繼資料。
- externalDocs - 其他外部文件參考
註解可以存在於 Swagger 執行階段掃描的任何類別上。例如，您的專案中可以有一個只有此註解的空介面 - 以便將一般 API 中繼資料與 API 資源特定的中繼資料分開。例如，將此註解放在標準 JAX-RS 資源旁邊
@SwaggerDefinition(
info = @Info(
description = "我的 API",
version = "V1.2.3",
title = "您唯一需要了解我的 API",
termsOfService = "分享與關懷",
contact = @Contact(name = "海綿寶寶", email = "[email protected]", url = "https://swagger.dev.org.tw"),
license = @License(name = "Apache 2.0", url = "http://www.apache.org"),
consumes = {"application/json" },
produces = {"application/json" },
schemes = {SwaggerDefinition.Scheme.HTTP, SwaggerDefinition.Scheme.HTTPS},
externalDocs = @ExternalDocs(value = "關於我", url = "http://about.me/me")
)
public interface MyApiDefinition {}
結果會將其新增至產生的 Swagger 定義
{
"swagger": "2.0",
"info": {
"description": "我的 API",
"version": "V1.2.3",
"title": "您唯一需要了解我的 API",
"termsOfService": "分享與關懷",
"contact": {
"name": "海綿寶寶",
"url": "https://swagger.dev.org.tw",
"email": "[email protected]"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org"
},
"schemes": [
"http",
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
...
您可以在 wiki 和其對應的 javadoc 中閱讀更多關於 SwaggerDefinition 註解的資訊。
@Extension
擴充功能註解可讓您將 擴充功能屬性新增至 Swagger 定義。目前在 @ApiOperation、@Info 和 @Tag 註解中支援。有兩種使用方法
...
extensions = {
@Extension(properties = {
@ExtensionProperty(name = "test1", value = "value1"),
@ExtensionProperty(name = "test2", value = "value2")
})
}
...
結果會產生以下 JSON
...
"x-test1" : "value1",
"x-test2" : "value2"
...
如果註解中未明確執行，則屬性名稱會自動加上 "x-" 前綴。
或者，您可以命名擴充功能
...
extensions = {
@Extension( name = "my-extension", properties = {
@ExtensionProperty(name = "test1", value = "value1"),
@ExtensionProperty(name = "test2", value = "value2")
})
}
...
結果會產生以下 JSON
...
"x-my-extension" : {
"test1" : "value1",
"test2" : "value2"
}
...
這會將包含的擴充功能屬性包裝在 JSON 物件中。
ReaderListener
如果這些註解擴充功能仍然無法協助您以您想要的方式製作 Swagger 定義，您可以選擇建立一個 ReaderListener，它將在 Swagger 執行階段之前和之後被叫用。此擴充功能會讀取所有 Swagger 和 JAX-RS 註解，並建立對應的 Swagger 定義。實作任一處理常式讓您可以完全控制產生的定義，讓您可以隨意變更
- 新增安全性定義或自訂模型物件
- 根據某些內容屬性篩選出不必要的資訊
- 讀取並新增在其他地方定義的 API 定義
- 等等。
您只需要提供一個實作 ReaderListener 介面的類別，並確保 Swagger 執行階段使用的類別路徑掃描器可以找到該類別。如果您建立如上所示的 @SwaggerDefinition 註解介面，您可以將其變更為類別，並在其中實作此介面
@SwaggerDefinition(...)
public class MyApiDefinition implements ReaderListener {
public static final String TOKEN_AUTH_SCHEME = "tokenAuthScheme";
public static final String ACCOUNT_READ_SCOPE = "account_read";
public static final String ACCOUNT_WRITE_SCOPE = "account_write";
@Override
public void beforeScan(Reader reader, Swagger swagger) {
}
@Override
public void afterScan(Reader reader, Swagger swagger) {
OAuth2Definition tokenScheme = new OAuth2Definition();
tokenScheme.setFlow("password");
tokenScheme.setTokenUrl("https://" + swagger.getHost() + "/tokens");
Map<String, String> scopes = new HashMap<>();
scopes.put(ACCOUNT_READ_SCOPE, "讀取我的資料");
scopes.put(ACCOUNT_WRITE_SCOPE, "更新我的資料");
tokenScheme.setScopes(scopes);
swagger.addSecurityDefinition(TOKEN_AUTH_SCHEME, tokenScheme);
}
}
此範例會新增 OAuth2 密碼憑證授權安全性定義，您可以使用類似的方式在 @ApiOperation 註解中參考該定義
@ApiOperation(value = "Updates user data",
authorizations = @Authorization(value = MyApiDefinition.TOKEN_AUTH_SCHEME, scopes =
@AuthorizationScope(scope = MyApiDefinition.ACCOUNT_WRITE_SCOPE, description = "寫入使用者資料的權限"))
public Response updateUser( UserData data ) throws NotFoundException {
...
}
由於 ReaderLicenser 是 Swagger Core 專案中 JAX-RS 實作模組特有的，因此它位於 io.swagger.swagger-jaxrs 模組中，而不是像上述其他模組一樣位於 io.swagger.swagger-annotations 中。
對註解的更多改進
以上並非對 Swagger 註解所做的唯一改進和新增功能 - 我們還
一如既往 - 如果您遺漏了任何內容或發現問題 - 請透過 Google 群組 或 GitHub 與我們聯繫，以便我們可以解決問題並使 Swagger 變得更好！