虚张声势的继承与创作

Question

在我的“简化”API中，所有响应都是从基本“响应”类派生（继承）的。响应类由一个填充元数据的头和一个包含用户请求的核心数据的主体组成。响应（在JSON中）的布局使得所有元数据都在第一个“层”上，而主体是一个称为“主体”的单一属性

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规范（如下所示）中找不到继承的例子，但找到了组合的例子。

我很确定这个“鉴别器”有很大的作用，但不确定我需要做什么。

有人能告诉我如何在swagger 2.0（JSON）中实现组合继承吗？最好是通过“修复”下面的示例代码。如果我可以指定一个从response继承的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对象中，这是在filename_response使用基本response_body类的filename_response_body子类的情况下完成的。错误和成功响应都使用“response”对象。

Answer 1

这里的所有答案都已经很好了，但是我只想补充一点关于组合和继承的小注意。根据Swagger/OpenAPI规范，要实现组合，使用allOf属性就足够了，正如@oblalex正确指出的那样。但是，要实现继承，您需要将allOf与鉴别器一起使用，如@TomaszSétkowski的示例所示。

此外，我在API Handyman中找到了更多关于组合和继承的Swagger示例。它们是Arnaud Lauret的优秀Swagger/OpenAPI教程系列的一部分，我认为每个人都应该看看。

Answer 2

我发现，即使没有鉴别器的定义，合成也能正常工作。

例如，baseResponse：

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

呈现为：

我们可以扩展它来细化结果字段的自定义模式：

  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足以工作，并且不使用鉴别器字段。这很好，因为它可以工作，这很重要，正如我认为的，工具将能够在没有鉴别器字段的情况下生成代码。

Answer 3

作为一个招摇过市的初学者，我不觉得有关polimorphism和composition的官方文档很容易理解，因为它缺少一个例子。当我在网上搜索时，有很多很好的例子提到了当extends有效时的swagger 1.2。

对于swagger 2.0，我通过这个google小组在github上的swagger规范源代码中找到了一个很好的例子

基于以上来源，下面是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