`<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: 用户API
  version: '1.0'
servers:
  - url: https://jsonplaceholder.typicode.com
    description: Json占位符服务
paths:
  /users/{id}:
    parameters:
      - schema:
          type: integer
        name: id
        in: path
        required: true
    get:
      summary: 按ID获取用户
      tags:
        - 用户
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
      operationId: get-users-user_id
      description: 按ID检索特定用户

上述YAML是一个非常简单的OpenAPI规范，定义了一个通过ID获取用户详细信息的API。

同样，我们也有等效的名为_sample.json_的JSON文档文件：

{
  "openapi": "3.0.0",
  "info": {
    "title": "用户API",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://jsonplaceholder.typicode.com",
      "description": "Json占位符服务"
    }
  ],
  "paths": {
    "/users/{id}": {
      "parameters": [
        {
          "schema": {
            "type": "integer"
          },
          "name": "id",
          "in": "path",
          "required": true
        }
      ],
      "get": {
        "summary": "按ID获取用户",
        "tags": [
          "用户"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get-users-user_id",
        "description": "按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上找到。