使用URI Swagger外部文件$ ref

Question

技术与版本：

• Swagger 2.0（使用json，而不是yaml）
• JSON.NET Schema（Newtonsoft.Json：10.0.0.2，Newtonsoft.Json.Schema：3.0.4）

需求：

使用Swagger进行“深层嵌套引用”。作为最终结果，我想要一个主要的swagger文件，$ ref一个外部文件用于路径参数/响应定义，然后外部文件应该能够$ ref在同一个文件中的子定义。

至今：

我正在使用JSON.NET Schema库来运行我们的程序集并以json格式创建swagger模式。然后从我们的主swagger.json文件手动引用它们。我有2个结果：

1. 生成外部文件没有$ ref定义，所有内联，然后当我从swagger.json我ref $外部文件时，一切都很好的天堂。
2. 使用$ ref定义生成外部文件，然后当我从swagger.json中获取外部文件时，外部文件中的$ ref都不能被解析。

我想让结果2工作。

例如，如果我有以下两个文件，我想要“$ ref”：“＃/ definitions / Education”部分工作。 swaggerSchemas.json输出是我从JSON.NET Schema生成器获得的。我已经尝试将“Person”中的“定义”移动到swaggerSchemas.json的根json包装中，但这也不起作用。当我说“它不起作用”时，我的意思是Swagger不喜欢它。应用程序死于Swagger验证错误。

swagger.json

{
    "swagger": "2.0",
    "info": {
        "version": "0.0.1",
        "title": "ASDF"
    },
    "basePath": "/",
    "schemes": [
        "http",
        "https"
    ],
    "consumes": [
        "application/json",
        "application/octet-stream"
    ],
    "produces": [
        "application/json"
    ],
    "paths": {
        "/person": {
            "x-swagger-router-controller": "PersonController",
            "get": {
                "x-function": "find",
                "description": "Default Description",
                "tags": [
                    "gen"
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "$ref": "swaggerSchemas.json#/Person"
                        }
                    },
                    "default": {
                        "$ref": "#/responses/ErrorResponse"
                    }
                }
            }
        }
    }
}

swaggerSchemas.json

{
    "Person": {
        "definitions": {
            "education": {
                "type": "object",
                "properties": {
                  "highestQualification": {
                    "type": "string"
                  },
                  "extraData": {
                    "type": [
                      "string",
                      "number",
                      "integer",
                      "boolean",
                      "object",
                      "array"
                    ]
                  }
                },
                "required": [
                  "highestQualification",
                  "extraData"
                ]
            }
        },
        "type": "object",
        "properties": {
            "userId": {
                "type": "string"
            },
            "firstNames": {
                "type": "string"
            },
            "surname": {
                "type": "string"
            },
            "education": {
                "$ref": "#/definitions/Education"
            }
        }
    }
}

这种行为，即Swagger 2.0可以使用的“深度嵌套$ ref”吗？

如果是这样，我如何在JSON.NET Schema中实现这一目标？

Answer 1

swaggerSchemas.json文件的结构看起来不有效：

{
  "Person": {
    "definitions": {
      "education": {
        "type": "object",
        ...
      }
    },

    "type": "object",
    ...
  }
}

包含多个模式的文件应如下所示。根标签名称可以是任意的，但通常使用definitions。

{
  "definitions": {

    // "Education", not "education".
    // The letter case of the schema name must be the same as used in the $ref below.
    "Education": {
      "type": "object",
      ...
    },

    "Person": {
      "type": "object",
      "properties": {
        ...,
        "education": {
          "$ref": "#/definitions/Education"
        }
      }
    }

  }
}

此外，在主文件中，更改

"$ref": "swaggerSchemas.json#/Person"

至

"$ref": "swaggerSchemas.json#/definitions/Person"

反映swaggerSchemas.json文件中的新节点结构（definitions - > Person）。