AWS API网关的OpenAPI / Swagger模型继承

Question

我正在尝试使用AWS API网关实现Swagger或OpenAPI 3.0中定义的API。

这个API中的一个endpoint采用一个抽象的基本模型(让我们称之为< code>Pet以与老套的Swagger示例保持一致)，但实际上期望一个从< code>Pet派生的具体模型...例如< code>Dog。

具体模型可以通过Pet上的类型（type）属性确定。

当然，这是一个歧视者的工作：

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

(取自此处)

好吧，很烦人，但也许一个解决方法是用OpenAPI 3.0定义API，并在模式中使用< code>oneOf:

paths:
    /pets:
        patch:
            requestBody:
                content:
                    application/json:
                        schema:
                            oneOf:
                                - $ref: '#/components/schemas/Cat'
                                - $ref: '#/components/schemas/Dog'

然而(再次)，AWS API网关也不支持< code > one of (ref)。

Answer 1

这可能不是完全令人满意的答案，但有一种方法可以将 oneOf 与 API 网关配合使用。您可以根据 AWS 对各个模型使用 JSON 架构。

由于这一事实，您可以在部署API网关后更新模型。

# Reformatted here for readability
VALUE='"{\"$schema\": \"http://json-schema.org/draft-04/schema#\",
         \"title\": \"A Pet Request\",
         \"oneOf\":
        [{ \"$ref\": \"https://apigateway.amazonaws.com/restapis/xxxxxxx/models/Cat\" },
         { \"$ref\": \"https://apigateway.amazonaws.com/restapis/xxxxxxx/models/Dog\" }]}"'


aws apigateway update-model \
--rest-api-id xxxxxxx \
--model-name 'PetRequest' \
--patch-operations "op=replace,path=/schema,value=${VALUE}"

但是，这种解决方案可以工作，可能不太可持续，因为您需要在每次部署后执行修补程序操作。

Answer 2

以下是工作示例：

{
  "openapi": "3.0.1",
  "info": {
    // (...)
  },
  "paths": {
    "/pets": {
      "post": {
        "summary": "Post a pet",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PetRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            // (...)
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Cat": {
        "type": "object",
        "required": [
          "cat_stuff"
        ],
        "properties": {
          "cat_stuff": {
            "type": "string"
          }
        }
      },
      "Dog": {
        "type": "object",
        "required": [
          "dog_stuff"
        ],
        "properties": {
          "dog_stuff": {
            "type": "string"
          },
        }
      },
      "PetRequest": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/Cat"
          },
          {
            "$ref": "#/components/schemas/Dog"
          }
        ]
      }
    },
    // Many fields omitted (...)
}

使用与其中一个模式不匹配的有效负载会产生以下错误，这证明< code>oneOf正在按预期工作！

(...)
"error_messages": [
    "[instance failed to match exactly one schema (matched 0 out of 2)]"
],