Swagger 继承和组合

Question

在我的“简化”API 中，所有响应均从基本“响应”类派生(继承)。响应类由填充元数据的 header 和包含用户请求的核心数据的正文组成。响应(JSON 格式)的布局使得所有元数据都位于第一个“层”，而正文是一个名为“body”的单个属性

response
|--metadata attribute 1 (string/int/object)
|--metadata attribute 2 (string/int/object)
|--body (object)
    |--body attribute 1 (string/int/object)
    |--body attribute 2 (string/int/object)

我尝试使用以下 JSON 来定义这种关系:

{
    ...
    "definitions": {
        "response": {
            "allOf": [
                {
                    "$ref": "#/definitions/response_header"
                },
                {
                    "properties": {
                        "body": {
                            "description": "The body of the response (not metadata)",
                            "schema": {
                                "$ref": "#/definitions/response_body"
                            }
                        }
                    }
                }
            ]
        },
        "response_header": {
            "type": "object",
            "required": [
                "result"
            ],
            "properties": {
                "result": {
                    "type": "string",
                    "description": "value of 'success', for a successful response, or 'error' if there is an error",
                    "enum": [
                        "error",
                        "success"
                    ]
                },
                "message": {
                    "type": "string",
                    "description": "A suitable error message if something went wrong."
                }
            }
        },
        "response_body": {
            "type": "object"
        }
    }
}

然后，我尝试通过创建从 body/header 继承的各种 body/header 类来创建不同的响应，然后创建由相关 header/body 类组成的子响应类(如底部的源代码所示)。但是，我确信这要么是错误的做事方式，要么是我的实现不正确。我一直无法在swagger 2.0 specification中找到继承的例子(如下所示)但找到了 composition 的示例.

我非常确定这个“鉴别器”可以发挥很大的作用，但不确定我需要做什么。

问题

有人可以告诉我如何在 swagger 2.0 (JSON) 中实现组合+继承，最好是通过“修复”下面的示例代码。如果我可以指定一个继承自响应的 ErrorResponse 类，其中 header 中的“结果”属性始终设置为“错误”，那就太好了。

{
    "swagger": "2.0",
    "info": {
        "title": "Test API",
        "description": "Request data from the system.",
        "version": "1.0.0"
    },
    "host": "xxx.xxx.com",
    "schemes": [
        "https"
    ],
    "basePath": "/",
    "produces": [
        "application/json"
    ],
    "paths": {
        "/request_filename": {
            "post": {
                "summary": "Request Filename",
                "description": "Generates an appropriate filename for a given data request.",
                "responses": {
                    "200": {
                        "description": "A JSON response with the generated filename",
                        "schema": {
                            "$ref": "#/definitions/filename_response"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "response": {
            "allOf": [
                {
                    "$ref": "#/definitions/response_header"
                },
                {
                    "properties": {
                        "body": {
                            "description": "The body of the response (not metadata)",
                            "schema": {
                                "$ref": "#/definitions/response_body"
                            }
                        }
                    }
                }
            ]
        },
        "response_header": {
            "type": "object",
            "required": [
                "result"
            ],
            "properties": {
                "result": {
                    "type": "string",
                    "description": "value of 'success', for a successful response, or 'error' if there is an error",
                    "enum": [
                        "error",
                        "success"
                    ]
                },
                "message": {
                    "type": "string",
                    "description": "A suitable error message if something went wrong."
                }
            }
        },
        "response_body": {
            "type": "object"
        },
        "filename_response": {
            "extends": "response",
            "allOf": [
                {
                    "$ref": "#definitions/response_header"
                },
                {
                    "properties": {
                        "body": {
                            "schema": {
                                "$ref": "#definitions/filename_response_body"
                            }
                        }
                    }
                }
            ]
        },
        "filename_response_body": {
            "extends": "#/definitions/response_body",
            "properties": {
                "filename": {
                    "type": "string",
                    "description": "The automatically generated filename"
                }
            }
        }
    }
}

图表更新

为了尝试阐明我想要的内容，我创建了下面的非常基本的图表，其目的是显示所有响应都是“响应”对象的实例，该对象是通过(组合)使用response_header和response_body对象的任意组合构建的。可以扩展response_header和response_body对象并将其插入到任何响应对象中，这是在使用response_body基类的filename_response_body子级的filename_response的情况下完成的。错误和成功响应都使用“response”对象。

Answer 1

作为 swagger 的初学者，我找不到 official documentation关于多态性和组合很容易理解，因为它缺乏示例。我上网一搜，有很多good examples引用 swagger 1.2 当 extends 有效时。

对于swagger 2.0，我在 swagger spec sources on github 中找到了一个很好的例子通过这个google group

根据上述来源，这里是 YAML 中的一个简短的有效继承示例:

definitions:
  Pet:
    discriminator: petType
    required:
      - name
      - petType # required for inheritance to work
    properties:
      name: 
        type: string
      petType:
        type: string
  Cat:
    allOf:
      - $ref: '#/definitions/Pet' # Cat has all properties of a Pet
      - properties: # extra properties only for cats
          huntingSkill:
            type: string
            default: lazy
            enum:
              - lazy
              - aggressive
  Dog:
    allOf:
      - $ref: '#/definitions/Pet' # Dog has all properties of a Pet
      - properties: # extra properties only for dogs
          packSize:
            description: The size of the pack the dog is from
            type: integer