如何在 Java 中將 OpenAPI 2.0 轉換為 OpenAPI 3.0
一、簡介
儘管 OpenAPI 3.x 規格自 2017 年以來已經推出，並經歷了多次更新，但許多 API 仍在使用舊版。
在本教程中，我們將探討OpenAPI 2.0和OpenAPI 3.0規格之間的主要區別，並學習從舊版升級到更新版本的不同方法。
2.OpenAPI 2.0 與 OpenAPI 3.0
簡單回顧一下， OpenAPI提供了一種標準格式來描述人類和機器可讀的 HTTP API。在 3.0 版本之前，OpenAPI 被稱為 Swagger 規範，並且是Swagger工具包的一部分。從那時起，它已成為行業標準，並進行了多次更新，帶來了額外的改進和功能。
與 2.0 相比，OpenAPI 3.0 引入了幾個根本性的變化。
首先，重新安排了整體結構以提高可重複使用性。新增了一個components區塊來組織現有元素，例如schemas 、 responses 、 parameters和新元素 - requestBody 、 examples和headers 。一些元素被重新命名 - definitions現在稱為schemas ， securityDefinitions是securitySchemes 。
此外，OpenAPI 3.0 進一步擴充了 JSON Schema 功能。新增了諸如oneOf 、 anyOf和not的關鍵字，以允許複雜資料格式的描述和靈活驗證。
接下來， 3.0版本引入了對cookie參數、內容類型協商和回呼機制的支援。它還擴展了其安全定義並簡化了現有流程。
總之，完整的更改清單可在官方更改日誌中找到。
3. 項目設定
讓我們繼續設定一個項目。通常，我們會公開 REST 服務並使用OpenAPI 來定義和記錄 API 。但是，由於我們要將 OpenAPI 規範的 2.0 版本轉換為較新的版本，因此讓我們使用公開可用的**API 。**
雖然YAML規範版本也可用，但我們將重點放在**JSON**格式。因此，讓我們下載該文件並將其放置在我們的resources資料夾中。這樣，就可以輕鬆地示範轉換規範的不同方法。根據方法，我們將透過瀏覽器或curl上傳文件，將其作為參數傳遞，或在程式碼中引用它。
4. 工具和函式庫
使用 OpenAPI 規範時，有多種工具和函式庫可供選擇。讓我們先回顧一下不需要本機安裝的選項，這些選項允許我們直接在瀏覽器中轉換 API 規格版本。
4.1.招搖編輯器
除其他功能外， Swagger Editor還允許我們上傳或貼上 API 規範並將其轉換為 OpenAPI 3.0 或其他格式。讓我們提供規範，從Edit選項下的選單中選擇Convert to OpenAPI 3 ，然後等待轉換完成：
完成後，新版本的規範將自動可用。
4.2.招搖轉換器
接下來， Swagger Converter工具的線上版本提供了兩種轉換規範的方法。
第一個允許透過上傳檔案或貼上 JSON 內容直接提供 OpenAPI 2.0 規格：
curl -X 'POST' \
'https://converter.swagger.io/api/convert' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
--data-binary @swagger.json如果 API 是可公開存取的，我們可以透過引用指向舊版 API 規範的 URL 來轉換規格：
curl -X 'GET' \
'https://converter.swagger.io/api/convert?url=https%3A%2F%2Fpetstore.swagger.io%2Fv2%2Fswagger.json' \
-H 'accept: application/json'Swagger Converter支援JSON和YAML格式，並提供使用者友善的UI以方便轉換。
4.3. API 規格轉換器
對於公共 API，另一個選擇是[api-spec-converter](https://lucybot-inc.github.io/api-spec-converter/) ，這是一個支援各種 API 規範格式的開源程式庫。讓我們提供一個 URL，選擇OpenAPI 2 (Swagger)作為Source並OpenAPI 3.0作為Destination Format ，然後按一下Convert ：
成功完成後，轉換後的規格將可供下載。
現在讓我們來探索具有 CLI 和外掛程式版本的其他工具。
4.4. Swagger 代碼產生器
Swagger Codegen是一個開源程式碼產生器。除了建立 REST 用戶端、產生伺服器存根和各種格式的 API 文件之外，我們還可以使用該程式庫來轉換規格。
讓我們下載最新版本並執行以下命令：
java -jar swagger-codegen-cli-3.0.62.jar generate \
-l openapi \
-i https://petstore.swagger.io/v2/swagger.json \
-o converted結果是位於指定輸出資料夾中的 OpenAPI 3.0 規格（在我們的範例中converted ）。
透過選擇不同的命令列選項，我們可以自訂生成過程。例如，在上面的範例中，設定為openapi語言（ -l或–lang ）將產生 JSON。要取得 YAML 格式的規範，我們需要將其設定為openapi-yaml 。
4.5. OpenAPI 產生器
如果我們使用 OpenAPI Generator，轉換過程看起來類似，因為它是 Swagger Codegen 的分支。使用最新版本，讓我們執行以下命令：
java -jar openapi-generator-cli-7.9.0.jar generate \
-g openapi \
-i https://petstore.swagger.io/v2/swagger.json \
-o converted同樣，我們可以透過選擇不同的生成器名稱（ -g ）選項（例如openapi-yaml或openapi來產生 YAML 或 JSON 格式的規格。
需要注意的是，在 CLI 中執行 JAR 檔案時，Java 版本必須相容。否則，我們可能會遇到UnsupportedClassVersionError ，這表示版本不符。
4.6. Swagger 解析器
顧名思義， Swagger Parser幫助我們解析 OpenAPI 文件。此外，我們可以使用它將舊版本的規範轉換為新版本的規範。
按照 Swagger 解析器的使用說明，讓我們建立一個處理規範檔案的簡單方法：
private static OpenAPI processSpecificationJson(final String specificationFileLocation) {
SwaggerParseResult result = new OpenAPIParser().readLocation(specificationFileLocation, null, null);
final OpenAPI openAPI = result.getOpenAPI();
if (openAPI == null) {
throw new IllegalArgumentException("Failed to parse OpenAPI specification from: "
+ specificationFileLocation);
}
return openAPI;
}接下來，我們可以使用ObjectMapper的writeValueAsString()方法將 OpenAPI 物件序列化為 JSON：
private static String asJsonString(OpenAPI openAPI) throws JsonProcessingException {
return objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(openAPI);
}
透過設定對應的屬性，我們使 JSON 輸出更具可讀性並排除了null值：
private static final ObjectMapper objectMapper;
static {
objectMapper = new ObjectMapper();
objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
}此時，我們可以定義轉換方法：
public static String convert(String specificationFileLocation) throws IOException {
if (specificationFileLocation == null || specificationFileLocation.isEmpty()) {
throw new IllegalArgumentException("Specification file path cannot be null or empty.");
}
return asJsonString(processSpecificationJson(specificationFileLocation));
}最後，我們的測試透過確保結果不會為null來驗證轉換過程：
@Test
void givenOpenApi2_whenConvert_thenSpecificationSuccessfullyConverted() throws IOException {
String openAPI3 = SwaggerToOpenApiConverter.convert(FILE_OPEN_API_2_SPECIFICATION);
assertNotNull(openAPI3);
}成功的測試顯示 OpenAPI 2 已正確轉換。
5. 結論
在本教學中，我們示範了將 OpenAPI 2.0 規格轉換為 OpenAPI 3.0 的幾個選項。我們探索了各種工具和函式庫，包括 Swagger Editor 和 Converter 等線上選項以及 Swagger Codegen 和 OpenAPI Generator 等命令列工具。
由於它們提供類似的轉換功能，我們的選擇取決於 API 是否公開、我們對工具的熟悉程度以及我們需要實現的附加功能。
與往常一樣，完整的源代碼可以 在 GitHub 上取得。