打开 Api $ref 使用 url答案

【问题标题】：Open Api $ref to use url打开 Api $ref 使用 url
【发布时间】：2020-02-23 10:38:59
【问题描述】：

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

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

这是 apen api 文档的示例：

(doc.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，输入得到验证，一切正常。

由于端点的变化（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？

【问题讨论】：

嗨詹姆斯。我正在努力完全理解您的问题。您能否重新阅读并检查您是否包含了您想要包含的所有内容，格式和故事/解释是否正确？
另外，您应该注意，您不能直接或通过引用在 OpenAPI 规范文件中简单地使用 JSON Schema Draft-7。对于 OAS 3.1，这可能会发生变化。到目前为止，您可能很幸运，您还没有使用任何不受支持的东西（如果不查找，我就记不起列表了）。
此外，由于我目前无法解决您的具体问题，您可能会发现草案 7 规范文档的这一部分有助于了解在使用位置时取消引用在 JSON Schema 中的工作方式-独立标识符：tools.ietf.org/html/draft-handrews-json-schema-01#section-8.2.4

标签： java json swagger jsonschema openapi

【解决方案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'

【讨论】：