昂首阔步的继承与组成


81

在我的“简化” API中,所有响应都是从基本“响应”类派生(继承)的。响应类填充有元数据的标头和包含用户请求的核心数据的正文组成。布置响应(以JSON格式),使得所有元数据都位于第一个“层”上,并且body是这样一个称为“ 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规范(如下所示)中找到继承的示例,但是找到了composition的示例。

在此处输入图片说明

我可以肯定的是,这个“判别器”有很大的作用,但是不确定我需要做什么。

有人可以告诉我如何在swagger 2.0(JSON)中实现构图和继承,最好是通过“固定”下面的示例代码来实现。如果我可以指定一个从响应继承的ErrorResponse类,那也很好,其中标题中的“结果”属性始终设置为“错误”。

{
    "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”对象的实例。可以扩展response_header和response_body对象并将其插入到任何响应对象中,这在使用基本response_body类的filename_response_body子项的filename_response的情况下完成。错误响应和成功响应都使用“响应”对象。

在此处输入图片说明


1
还有就是对组成样本,但它是如此糟糕,这是不值得的共享。我将研究您的规格外观。请记住,UI当前不支持它,但是在完全支持2.0时它将支持。
罗恩,2015年

1
在我潜入之前,还有一件事-您要寻找组成还是继承?作文基本上是在说I have the properties of X and my own properties.。继承暗示着一种关系X is my parent. I have its properties and my own.。如果要说正在使用某些适用于父模型的模型,则继承很有用。
罗恩

1
我本来希望通过这个例子一并演示继承组合的使用。显然,我意识到一个人可以很容易地单独使用其中之一,但是在这种情况下,所有响应都是基本“响应”类的子级。响应类由其他两个对象“标头”和“主体”“组成”。
Programster

2
我可能还不清楚。继承是组合的扩展。如果有继承,那就有组成。如果有组成,就不一定有继承。另外,在您的示例中,“响应”模型没有在任何地方使用。我应该忽略它,只是显示它的外观吗?
罗恩

嗯,没有意识到继承与构图之间的关系。因此,使用继承来显示两者。关于未使用的响应模型,应将其与请求响应的filename_response子代中的“扩展”一起使用。
Programster

Answers:


113

作为草率的初学者,我发现有关政治形态和构成的官方文档不容易理解,因为它缺乏示例。当我在网上搜索时,有很多很好的例子都提到extends有效的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

真的感谢!这对我有用。在中editor.swagger.io,我看到一个小错误:在模型部分中,我Pet多次看到该模型。这些模型的内容还可以。只有名称错误。
schellingerht

@schellingerht在editor2.swagger.io您中您不会看到此问题
Shiplu Mokaddim

我用这种定义继承的方法发现的唯一问题是,petType属性在生成的类中有点没用。它是空的。但是至少它确实像我想的那样生成了类层次结构。谢谢!
xarlymg89

为了如上所述创建继承json,必须注释父级和子级类,如下所示:@ApiModel(discriminator =“ type”,subTypes = {Cat.class,Dog.class})公共抽象类Animal {} @ ApiModel(parent = Animal.class)public calss猫继承了Animal {}
Janet

区分符仅在实现接口时才使用Pet,如果A类扩展了B类,我们也应该使用它吗?谢谢
Bionix1441

23

我发现即使没有的定义,合成也可以正常工作discriminator

例如,base 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

它将正确呈现为:

FooServiceResponse可视化

请注意,这allOf足以满足要求,并且不discriminator使用任何字段。这很好,因为它有效并且很重要,正如我认为的那样,工具将能够在没有discriminator字段的情况下生成代码。


我也用过了allOf,但是在某种程度上openapi.yaml,我发现子类以冗余的方式包含了超类的属性,对吗?
Bionix1441

8

这里所有的答案都已经很好了,但是我只想添加一点关于构图与继承的注释。根据Swagger / OpenAPI Spec,要实现组合,使用该allOf属性就足够了,正如@oblalex正确指出的那样。然而,为了实现继承,你需要使用allOfdiscriminator,如通过@TomaszSętkowski例子

另外,我在API Handyman上找到了更多有关组成继承的Swagger示例。它们是Arnaud Lauret出色的Swagger / OpenAPI教程系列的一部分,我认为每个人都应该签出。


1
@尽管发布相关链接是一个好的开始,但实际上是一个有用的答案,您还应该引用在链接中可以找到的相关文本。不鼓励仅链接的答案,因为链接经常会失效。
Stijn de Witt

3

您共享的Swagger 2.0标准示例描述了一种组合关系,特别是它捕获了“是一种”超类型/子类型关系,但是它本身并不是多态性。

如果您可以引用Pet的基本定义作为输入参数,然后选择Cat或输入Cat JSON对象作为输入请求的值,并使Swagger UI可以接受。

我无法直接使用它。

我能做的最好的事情是在基础对象(例如Pet)上将extraProperties设置为true,使用JSON指针引用作为输入架构指定Pet,最后将Cat JSON值对象复制并粘贴到Swagger UI中。由于允许附加属性,因此Swagger UI生成了有效的输入请求有效负载。


除非您想与特定的技术紧密结合以使其正常工作,否则您不必通过电线进行多态处理(或公开数据实体)。
user1496062 '16

多态通过继承启用,但使用继承不是必需的。从逻辑上讲,继承是“是”关系,而组成是“有”关系。取决于实现语言和域用例,两者之间的界限可能会模糊。但这是起点。首先,鉴别符可以实现多态类型的反序列化。还有其他方法(例如,包括Java类名)。但是,一致认为,这些可能是笨拙的,而不是可移植的。例如,python客户端将如何处理Java类名?
查理·赖茨
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.