为什么定义无法在此架构中显示？

Question

我正在尝试开发符合 swagger 规范的模式。见下文。参数和响应的定义 (model/schema) 未显示在 swagger-ui 界面中，所以我的问题是为什么。该模式通过了 swagger 验证器。

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "example",
    "description": "provides  various stuff",
    "termsOfService": "none",
    "contact": {
      "name": "admin",
      "url": "http://www.example.co.uk",
      "email": "hostmaster@example.com"
    },
    "license": {
      "name": "All Rights Reserved.",
      "url": "http://example.com"
    }
  },
  "host": "ofexample.co.uk",
  "basePath": "/",
  "schemes": [
    "https"
  ],
  "paths": {
    "/list": {
      "post": {
        "parameters": [
          {
            "name": "no_name",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#definitions/APIName"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#definitions/Versions"
            }
          }
        }
      }
    },
    "/ver/setdefault": {
      "post": {
        "parameters": [
          {
            "name": "no_name",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#definitions/App"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#definitions/App"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "APIName": {
      "type": "string"
    },
    "App": {
      "properties": {
        "name": {
          "type": "object",
          "$ref": "#/definitions/APIName",
          "description": "\n The name"
        },
        "id": {
          "type": "string",
          "description": "important field"
        },
        "version": {
          "type": "string"
        }
      }
    },
    "Versions": {
      "type": "string",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

Answer 1

规范本身几乎是正确的，只有 $ref 部分不对。例如，# 和 definitions/APIName 之间需要有一个 /。

      {
        "name": "no_name",
        "in": "body",
        "required": false,
        "schema": {
          "$ref": "#/definitions/APIName"
        }
      }

请注意，UI 由于存在错误，不会显示未引用的图元。为参数定义内联将正确显示它，但对于响应它不会。

另一个注意事项，虽然现在还没有明确定义，但如果没有 consumes/produces，将使用的 mime 类型是 application/json。如果您想使用文本，您可能需要将其设置为 text/plain 以传递字符串。

为什么定义无法在此架构中显示？

Why the definitions fail to be displayed in this schema?

swagger

swagger-ui