1. 引言
Swagger 是一套用于设计、描述和文档化 RESTful API 的工具集。
在这个教程中，我们将探索如何在 Java 中解析 OpenAPI 文件并提取其各个组件。
2. 什么是 Swagger？
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 验证器 工具。此外，Swagger 编辑器 提供了一个基于 GUI 的编辑器，帮助我们在运行时编辑和可视化 API 文档。
我们可以轻松地使用生成的 OpenAPI 文档与第三方工具一起使用，如 导入 Postman。
3. 使用 Swagger 解析器
Swagger 解析器是帮助我们解析 OpenAPI 文档并提取其各个组件的 Swagger 工具之一。 接下来，让我们看看如何在 Java 中实现解析器：
3.1. 依赖项
在开始之前，让我们将 Swagger 解析器的 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 文档受到保护，传递的授权头列表 -
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 上找到。