1. 引言
Swagger 是一套用於設計、描述和文檔化 RESTful API 的工具集。
在本教程中，我們將探索如何在 Java 中解析 OpenAPI 文檔文件並提取其各種組件。
2. Swagger 簡介
Swagger 基本上是一個開源的規則集、規範和工具，用於開發和描述 RESTful API。然而，隨着新標準和規範的不斷髮展，這些規範現在被重命名為 OpenAPI 規範 (OAS)。
OpenAPI 規範標準化了 API 設計文檔的創建方式。 它創建了一個我們可以輕鬆開發和消費的 RESTful 接口。API 規範有效地映射了與它相關的所有資源和操作。
一個 OpenAPI 文檔是一個自包含或組合的資源，它定義了 API 以及其各種元素。該文檔可以表示為 JSON 或 YAML 格式。
OpenAPI 規範的最新版本是 OAS 3.1。它允許我們指定 HTTP 資源、動詞、響應代碼、數據模型、媒體類型、安全方案和其他 API 組件。我們可以使用 OpenAPI 定義來生成文檔、代碼生成以及許多其他用例。
另一方面，Swagger 已經演變為開發 API 的最廣泛使用的開源工具集之一。 它基本上提供了一個完整的工具集，用於設計、構建和文檔化 API。
要驗證 OpenAPI 文檔，我們使用 Swagger 驗證器 工具。 此外，Swagger 編輯器 提供了一個基於 GUI 的編輯器，它幫助我們在運行時編輯和可視化 API 文檔。
我們可以輕鬆地使用生成的 OpenAPI 文檔與第三方工具（如導入到 Postman）一起使用。
3. 使用 Swagger Parser
Swagger Parser 是 Swagger 工具之一，它能幫助我們解析 OpenAPI 文檔並提取其各種組件。
接下來，讓我們看看如何在 Java 中實現解析器：
3.1. 依賴項
在開始之前，讓我們將 Swagger Parser 的 Maven 依賴項 添加到我們項目的 pom.xml 文件中：
<dependency>
<groupId>io.swagger.parser.v3</groupId>
<artifactId>swagger-parser</artifactId>
<version>2.1.13</version>
</dependency>接下來，我們來深入瞭解如何解析 OpenAPI 文檔。
3.2. 示例 OpenAPI 文檔
在開始之前，我們需要一些示例 OpenAPI 文檔供我們解析。我們使用以下示例 OpenAPI YAML 文檔 sample.yml：
openapi: 3.0.0
info:
title: User APIs
version: '1.0'
servers:
- url: https://jsonplaceholder.typicode.com
description: Json Place Holder Service
paths:
/users/{id}:
parameters:
- schema:
type: integer
name: id
in: path
required: true
get:
summary: Fetch user by ID
tags:
- User
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
type: integer
name:
type: string
operationId: get-users-user_id
description: Retrieve a specific user by ID上述 YAML 是一個非常簡單的 OpenAPI 規範，它定義了一個通過 ID 獲取用户詳細信息的 API。
同樣，我們還應該有一個名為 sample.json 的等效 JSON 文檔文件：
{
"openapi": "3.0.0",
"info": {
"title": "User APIs",
"version": "1.0"
},
"servers": [
{
"url": "https://jsonplaceholder.typicode.com",
"description": "Json Place Holder Service"
}
],
"paths": {
"/users/{id}": {
"parameters": [
{
"schema": {
"type": "integer"
},
"name": "id",
"in": "path",
"required": true
}
],
"get": {
"summary": "Fetch user by ID",
"tags": [
"User"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
}
}
}
},
"operationId": "get-users-user_id",
"description": "Retrieve a specific user by ID"
}
}
}
}我們將使用這些 OpenAPI 文檔文件作為所有我們的編碼示例。
現在，讓我們看看如何解析這個文檔。
3.3. 解析 OpenAPI YAML 文檔
首先，我們使用 OpenAPIParser().readLocation() 方法讀取和解析 YAML 或 JSON 文件。該方法接受三個參數：
- String – 我們想要讀取的文件 URL
- List<AuthorizationValue> – 如果要讀取的 OpenAPI 文檔受保護，則傳遞的授權標頭列表
- ParserOptions – 作為自定義解析行為的附加解析選項
首先，讓我們查看從 URL 讀取 OpenAPI 文檔的代碼片段：
SwaggerParseResult result = new OpenAPIParser().readLocation("sample.yml", null, null);readLocation() 方法返回一個 SwaggerParserResult 實例，其中包含解析結果。
其次，我們將使用返回的 SwaggerParserResult 實例來獲取解析的詳細信息：
OpenAPI openAPI = result.getOpenAPI();SwaggerParserResult.getOpenAPI() 方法返回一個 OpenAPI 類的實例。返回的 OpenAPI 類實例本質上是 OpenAPI 文檔的 POJO 版本。
最後，我們可以使用從獲得的 OpenAPI 實例中的各種 getter 方法來檢索 OpenAPI 文檔的各個組件：
SpecVersion version = openAPI.getSpecVersion();
Info info = openAPI.getInfo();
List<Server> servers = openAPI.getServers();
Paths paths = openAPI.getPaths();3.4. 解析 OpenAPI JSON 文檔
類似於之前的方法，我們也可以解析相應的 JSON 文檔文件。下面通過將文件名稱作為 URL，解析 sample.json 文件：
SwaggerParseResult result = new OpenAPIParser().readLocation("sample.json", null, null);此外，我們甚至可以使用 OpenAPIParser().readContents(String swaggerString, List<AuthorizationValue> auth, ParseOptions options) 方法從 String 中解析 OpenAPI Specification 文檔。
另外，通過調用 SwaggerParserResult.getMessages() 方法，可以獲取解析過程中產生的任何驗證錯誤和警告。該方法返回一個包含錯誤消息的字符串列表：
List<String> messages = result.getMessages();4. 結論
在本文中，我們探討了 OpenAPI 規範和 Swagger 的基本原理。
我們瞭解到如何使用 Java 解析 OpenAPI 文檔文件。我們實現瞭解析 YAML 和 JSON 規範文件代碼。
