打开Api $ref以使用url

Question

我在使用 open api v3 $ref 调用 URL 时遇到问题

我编写了一个开放 API v3 规范来提供 REST 应用程序的文档。我使用 $ref 来验证本文档的输入参数。这些 $refs 指向 url 中的 json 模式。

这是 apen api 文档的示例：

（文档.yml）

  /myapi:

      get:

        description: Some Description

        parameters:

          - name: profile

            in: query

            description: Some description

            required: false

            schema:

              $ref: 'http://localhost:8089/refs#/properties/profile'

端点http://localhost:8089/refs#/properties/profile正在返回

        "$schema": "http://json-schema.org/draft-07/schema#",

        "type": "object",

        "title": "Some Example",

        "definitions": {},

        "properties": {

            "profile": {

                "default": "",

                "examples": [

                    "1.0.0"

                ],

                "pattern": "^(\\d+\\.\\d+\\.\\d+)$",

                "type": "string",

                "title": "This is a version",

                "$id": "#/properties/profile"

            }

        },

        "$id": "myid1"

    }

我将 doc.yml 复制并粘贴到 swagger 中，输入经过验证，一切都很完美。

由于端点的更改（http://localhost:8089/refs）

我收到这样的回复：

  "oneOf": [

    {

      "$ref": "id1"

    }

  ],

  "$schema": "http://json-schema.org/draft-07/schema#",

  "description": "Some Description",

  "type": "object",

  "$id": "someid",

  "definitions": {

    "id1": {

      "description": "Some description",

      "additionalProperties": false,

      "type": "object",

      "title": "Some Example",

      "properties": {

        "profile": {

          "default": "",

          "examples": [

            "1.0.0"

          ],

          "pattern": "^(\\d+\\.\\d+\\.\\d+)$",

          "type": "string",

          "title": "The Version Schema",

          "$id": "#/properties/profile"

        }

      },

      "$id": "id1"

    }

  }

}

进行此更改后，Swagger 会抛出此错误。

“无法解析指针#/properties/profile”

我的问题是。当架构使用 oneOf 时，是否可以继续使用 #/properties/profile 作为 id？如果 json 模式使用 oneOf，如何让 open api 验证输入？我是否必须使用其他路径而不是#/properties/profile？

Answer 1

请记住，Open API 使用它自己的 JSON Schema 风格。它遗漏了一些东西，添加了一些东西，并修改了一些东西。目前，Open API 不支持$id/ id（参考： https: //swagger.io/docs/specification/data-models/keywords/）。好消息是您没有$id以任何有意义的方式使用它，因此仅将其忽略并不会改变您的情况。您的$ref: 'http://localhost:8089/refs#/properties/profile'路径不再有效，因为该路径不再存在。文档的结构已更改，因此 JSON 指针片段必须使用新的结构。它必须是$ref: 'http://localhost:8089/refs#/definitions/id1/properties/profile'