Swagger 解析器指南

一、簡介

Swagger是一組用於設計、描述和記錄 RESTful API 的工具。

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

2. 什麼是招搖？

Swagger 基本上是一組用於開發和描述 REST API 的開源規則、規範和工具。但是，隨著新標準和規範的發展，該規範現已更名為OpenAPI 規範(OAS)。

OpenAPI 規範標準化瞭如何創建 API 設計文檔。它創建了一個 RESTful 接口，我們可以使用它輕鬆開發和使用 API。 API 規範有效地映射了與之關聯的所有資源和操作。

OpenAPI 文檔是一種自包含或複合資源，它定義了 API 及其各種元素。該文檔可以用 JSON 或 YAML 格式表示。

最新版本的 OpenAPI 規範是OAS 3.1 。它允許我們指定 HTTP 資源、動詞、響應代碼、數據模型、媒體類型、安全方案和其他 API 組件。我們可以使用 OpenAPI 定義來生成文檔、代碼生成和許多其他用例。

另一方面， Swagger 已經發展成為用於開發 API 的最廣泛使用的開源工具集之一。它基本上提供了一個完整的工具集來設計、構建和記錄 API。

為了驗證 OpenAPI 文檔，我們使用Swagger Validator工具。此外， Swagger Editor提供了一個基於 GUI 的編輯器，可以幫助我們在運行時編輯和可視化 API 文檔。

我們可以很容易地將生成的 OpenAPI 文檔與第三方工具一起使用，例如導入到 Postman。

3. 使用 Swagger 解析器

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 規範，它定義了一個通過 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> – 如果要讀取的 OpenAPI 文檔受到保護，則要傳遞的授權標頭List
• 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 規範文檔。

此外，我們可以通過調用SwaggerParserResult.getMessages()方法在解析期間獲取任何驗證錯誤和警告。此方法返回包含錯誤消息的字符串列表：

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

4。結論

在本文中，我們了解了 OpenAPI 規範和 Swagger 的基礎知識。

我們看到瞭如何用 Java 解析 OpenAPI 文檔文件。我們實現了解析 YAML 和 JSON 規範文件的代碼。

一如既往，所有示例的完整代碼都可以在 GitHub 上找到。