首页 文章

使用URI Swagger外部文件$ ref

提问于
浏览 次
0

技术与版本：

  • Swagger 2.0（使用json，而不是yaml）

  • JSON.NET架构（Newtonsoft.Json：10.0.0.2，Newtonsoft.Json.Schema：3.0.4）

需求：

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

至今：

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

  • 生成没有$ ref定义的外部文件，全部内联，然后当我从swagger.json中获取外部文件时，一切都在天堂里 .

  • 使用$ 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中实现这一目标？

json.net swagger

1 回答

  • 0

    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 ） .

    回复于

相关问题