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

Question

假设我有一个 OpenAPI swagger.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 契约(Contract)。

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

Answer 1

在 OpenAPI 3.1 中，您可以直接引用您的 JSON 模式:

          # openapi: 3.1.0

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

早期的 OpenAPI 版本期望将 JSON 模式转换为 OpenAPI Schema Object格式(可以表示为 YAML 和 JSON)。必要的更改包括，例如:

• 删除unsupported keywords : $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 模式，但一些工具会在意外的关键字和构造上出错。