如何将 ref 用于示例 Swagger？

Question

JSON 规格：

"responses": {
          "200": {
            "description": "Успешный ответ сервиса",
            "schema": {
              "$ref": "#/definitions/BaseResponse"
            },
            "examples": {
              "application/json": {
                "status": true,
                "response": {
                  "$ref": "#/definitions/Product"
                },
                "errors": null
              }
            }
          }
}

结果：

但我需要：

{
  "status": true,
  "response": {
      "ProductNumber": "number",
      "Barcode": "number",
      "Length": 12,
      "Width": 34,
      "Height": 423,
      "Volume": 1232
    }
  },
  "errors": null
}

如何将 $refs 用于自定义格式响应的示例数组？这是一个典型案例，但我找不到相关文档。感谢您的反馈。

Answer 1

不支持内联示例$ref - 示例必须是完整示例：

      "responses": {
        "200": {
          "description": "Успешный ответ сервиса",
          "schema": {
            "$ref": "#/definitions/BaseResponse"
          },
          "examples": {
            "application/json": {
              "status": true,
              "response": {
                "ProductNumber": "number",
                "Barcode": "number",
                "Length": 12,
                "Width": 34,
                "Height": 423,
                "Volume": 1232
              },
              "errors": null
            }
          }
        }
      }

您可以在 BaseResponse 架构中指定示例值，而不是使用 responses.<code>.examples，Swagger UI 将使用这些值。

例如，您可以将完整的示例添加到您的 BaseResponse 架构中：

  "definitions": {
    "BaseResponse": {
      "type": "object",
      "properties": {
        "status": {
          "type": "boolean"
        },
        ...
      },
      "example": {    // <------ schema-level example
        "status": true,
        "response": {
          "ProductNumber": "number",
          "Barcode": "number",
          "Length": 12,
          "Width": 34,
          "Height": 423,
          "Volume": 1232
        },
        "errors": null
      }
    }
  }

或使用属性级例子：

  "definitions": {
    "BaseResponse": {
      "type": "object",
      "properties": {
        "status": {
          "type": "boolean",
          "example": true           // <------
        },
        "response": {
          "$ref": "#/definitions/Product"
        },
        "errors": {
          "example": null           // <------
        }
      }
    },
    "Product": {
      "type": "object",
      "properties": {
        "ProductNumber": {
          "type": "string",
          "example": "number"       // <------
        },
        "Length": {
          "type": "integer",
          "example": 12             // <------
        },
        ...
      }
    }
  }

我想指出 "errors": null 和 "example": null 在 OpenAPI 2.0 (fka Swagger) 中实际上无效，因为它不支持可空类型。可空类型仅在 OpenAPI 3.0 中 supported。

Answer 2

我尝试了很多解决方案，唯一似乎有效的是使用 'examples' 键而不是 'example'。然后放一个例子（你应该给它起名字），然后把 $ref 放在它下面。

就像这样：

"responses": {
          "200": {
            "description": "Успешный ответ сервиса",
            "schema": 
              "$ref": "#/definitions/BaseResponse"
            "examples":
              "example_name": # You can give as an example name any name you want
                $ref: "#/examples/200_res"

examples:
  200_res:
    description: example for 200_res
    value:
      {
        "status": true,
        "response": {
          "ProductNumber": "number",
          "Barcode": "number",
          "Length": 12,
          "Width": 34,
          "Height": 423,
          "Volume": 1232
        },
        "errors": null
      }

另请注意，在您添加的示例中，您的 { } 存在问题

如何将 ref 用于示例 Swagger？

How using ref into examples Swagger?

php

swagger

swagger-ui

swagger-2.0