如何将 ref 用于示例 Swagger? [英] How using ref into examples Swagger?

问题描述

JSON 规范:

响应":{200":{"description": "Успешный ответ сервиса",架构":{"$ref": "#/definitions/BaseResponse"},例子": {应用程序/json":{状态":真实，回复": {"$ref": "#/定义/产品"},错误":空}}}}

结果:

但我需要:

<代码>{状态":真实，回复": {"ProductNumber": "编号","条形码": "编号",长度":12，宽度":34，身高":423，卷":1232}},错误":空}

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

解决方案

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

响应":{200":{"description": "Успешный ответ сервиса",架构":{"$ref": "#/definitions/BaseResponse"},例子": {应用程序/json":{状态":真实，回复": {"ProductNumber": "编号","条形码": "编号",长度":12，宽度":34，身高":423，音量":1232},错误":空}}}}

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

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

定义":{基本响应":{类型":对象"，特性": {地位": {类型":布尔值"},...},"example": {//<------ 模式级示例状态":真实，回复": {"产品编号": "编号","条形码": "编号",长度":12，宽度":34，身高":423，卷":1232},错误":空}}}

或使用属性级示例:

定义":{基本响应":{类型":对象"，特性": {地位": {"类型": "布尔值","example": true//<------},回复": {"$ref": "#/定义/产品"},错误":{"example": null//<------}}},产品": {类型":对象"，特性": {产品编号": {类型":字符串"，"example": "number"//<------},长度": {"类型": "整数",示例":12//<------},...}}}

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

JSON spec:

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

Result:

But I need:

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

How I can using $refs into example array for custom format response? It's a typical case, but I cannot found documentation for it. Thank you for you feedback.

解决方案

Inline examples do not support $ref - the example must be a complete example:

      "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
            }
          }
        }
      }

Instead of using responses.<code>.examples, you can specify the example values in your BaseResponse schema, and Swagger UI will use those instead.

For example, you can add a complete example to your BaseResponse schema:

  "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
      }
    }
  }

or use property-level examples:

  "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             // <------
        },
        ...
      }
    }
  }

I'd like to note that "errors": null and "example": null are not actually valid in OpenAPI 2.0 (fka Swagger), because it does not support nullable types. Nullable types are supported in OpenAPI 3.0 only.

这篇关于如何将 ref 用于示例 Swagger?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！