如何将 JSON 架构合并到我的 OpenAPI 文件中？

Question

假设我有一个 OpenAPIswagger.yml文件，如下所示：

openapi: '3.0.2'
info:
  title: Simplest ever
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /test:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

我更喜欢将真实模式的来源保留在我的 schemas/ 目录中，例如schemas/get.json如下所示：

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    }
  }
}

目的是让 schemas/*.json 在我的后端代码库中使用，以验证传入和传出消息。目标是拥有强大的 API 合约。

我不明白的是如何swagger.yml使用这些 JSON 模式构建文件，而不是在 YAML 中重复工作，这确实很乏味且容易出错。

Answer 1

在 OpenAPI 3.1 中，您可以直接引用 JSON Schema：

          # openapi: 3.1.0

          content:
            application/json:
              schema:
                $ref: 'schemas/get.json'

早期的 OpenAPI 版本期望将 JSON 模式转换为OpenAPI 模式对象格式（可以表示为 YAML 和 JSON）。必要的改变包括，例如：

• 删除不支持的关键字：$schema、patternProperties、 等；
• 替换type: [<foo>, 'null']为type: <foo>+ nullable: true；
• type: [type1, type2, ...]用oneOf/替换其他类型数组anyOf(OAS3) 或删除它们 (OAS2)。

json-schema-to-openapi-schema可以自动转换。

您可以尝试$ref直接从 OAS 2.0 和 3.0 定义使用普通 JSON 模式，但某些工具会因意外关键字和构造而出错。