Question

在我的“简化”API中，所有响应都是从基础“响应”类派生的（ inherit ）。响应类是组成填充元数据的标头，以及包含用户请求的核心数据的主体。响应（在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 specification（如下所示）中找到继承的示例，但找到了composition的示例。

enter image description here

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

问题

有人可以告诉我如何在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子节点。错误和成功响应都使用“响应”对象。

enter image description here

Answer 1

作为一个招摇的初学者，我没有发现关于polimorphism和组合的official documentation很容易找不到，因为缺少一个例子。当我搜索网络时，extends有效时会有很多good examples引用swagger 1.2。

对于 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

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

这里的所有答案都已经很好了，但我只是想补充一点关于composition versus inheritance的备注。根据{{3}}，要实施合成，使用allOf属性就足够了Swagger/OpenAPI Spec。但是，要实施继承，您需要将allOf与discriminator一起使用，与@oblalex correctly points out中一样。

另外，我在API Handyman中找到了更多关于example by @TomaszSętkowski和composition的Swagger示例。他们是Arnaud Lauret inheritance的一部分，我想每个人都应该看看。

Answer 4

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

如果您可以将Pet的基本定义作为输入参数引用，那么选择Cat或输入Cat JSON对象作为输入请求的值，并将其接受为Swagger UI。

我无法让这个直接工作。

我能做的最好的工作是在基础对象（例如Pet）上将additionalProperties设置为true，使用JSON指针引用指定Pet作为输入模式，最后将我的Cat JSON值对象复制并粘贴到Swagger UI中。由于允许附加属性，Swagger UI生成了有效的输入请求有效负载。

摇摇欲坠的继承与构成

问题

图表更新

4 个答案: