摇摇欲坠的继承与构成

Question

在我的"简化"API中,所有响应都是从基础"响应"类派生(继承)的.响应类由填充元数据的标头和包含用户请求的核心数据的主体组成.响应(在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在swagger中定义这种关系:

{
    ...
    "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规范中找到继承的例子(如下所示),但已经找到了一个组合的例子.

我很确定这个"鉴别器"有很大的作用,但不确定我需要做什么.

题

有人可以告诉我如何在swagger 2.0(JSON)中实现组合+继承,最好通过"修复"下面的示例代码.如果我可以指定一个继承自响应的ErrorResponse类,其中标题中的"result"属性始终设置为"error",那也是很好的.

{
    "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对象可以扩展并插入到任何响应对象中,这在filename_response的情况下完成,该filename_response使用基本response_body类的filename_response_body子节点.错误和成功响应都使用"响应"对象.

Answer 1

作为一个招摇的初学者,我没有找到关于polimorphism和组成的官方文档很容易理解,因为它缺乏一个例子.当我搜索网络时,有很多很好的例子在extends有效的时候引用了swagger 1.2 .

对于swagger 2.0,我通过这个谷歌小组在github上找到了一个很好的例子

基于以上来源,这是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

Answer 2

我发现即使没有定义,组合也能正常工作discriminator.

例如,基数Response:

definitions:
  Response:
    description: Default API response
    properties:
      status:
        description: Response status `success` or `error`
        type: string
        enum: ["success", "error"]
      error_details:
        description: Exception message if called
        type: ["string", "object", "null"]
      error_message:
        description: Human readable error message
        type: ["string", "null"]
      result:
        description: Result body
        type: ["object", "null"]
      timestamp:
        description: UTC timestamp in ISO 8601 format
        type: string
    required:
      - status
      - timestamp
      - error_details
      - error_message
      - result

呈现为:

我们可以扩展它以改进result字段的自定义模式:

  FooServiceResponse:
    description: Response for Foo service
    allOf:
      - $ref: '#/definitions/Response'
      - properties:
          result:
            type: object
            properties:
              foo_field:
                type: integer
                format: int32
              bar_field:
                type: string
        required:
          - result

它将被正确呈现为:

注意,这allOf足以使其工作并且不discriminator使用任何字段.这很好,因为它很有用,这很重要,因为我认为,工具将能够生成没有discriminator字段的代码.

Answer 3

这里的所有答案都已经很好了,但我只想添加关于组合与继承的小注释.根据Swagger/OpenAPI规范,要实现组合,使用该allOf属性就足够了,正如@oblalex正确指出的那样.但是,要实现继承,您需要使用allOfwith discriminator,如@TomaszSętkowski中的示例.

此外,我在API Handyman中发现了一些更多Swagger 组合和继承的例子.他们是Arnaud Lauret 出色的Swagger/OpenAPI教程系列的一部分,我想每个人都应该看看.