1. 簡介

Swagger 是一套用於設計、描述和文檔化 RESTful API 的工具。

在本教程中，我們將探索如何在 Java 中解析 OpenAPI 文檔文件並提取其各種組件。

2. 什麼是 Swagger？

Swagger 基本上是一套開源的規則、規範和工具，用於開發和描述 REST 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 文檔，以便我們能夠解析它們。讓我們使用名為 sample.yml 的示例 OpenAPI YAML 文檔：

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 spec，它定義了一個通過 ID 檢索用户信息的 API。

同樣，我們還需要一個等效的 JSON 文檔文件，名為 sample.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> – List 包含授權頭，如果需要解析受保護的 OpenAPI 文檔，則使用
• ParserOptions – 作為一種方式來定製解析行為的額外的解析選項

首先，讓我們查看讀取 OpenAPI 文檔的 URL 代碼片段：

SwaggerParseResult result = new OpenAPIParser().readLocation("sample.yml", null, null);

readLocation() 方法返回一個 SwaggerParserResult 實例，其中包含解析結果。

OpenAPI openAPI = result.getOpenAPI();

SpecVersion version = openAPI.getSpecVersion();

Info info = openAPI.getInfo();

List<Server> servers = openAPI.getServers();

Paths paths = openAPI.getPaths();

SwaggerParseResult result = new OpenAPIParser().readLocation("sample.json", null, null);

List<String> messages = result.getMessages();