Question

我正在尝试使用Swagger记录REST API。我们API的简化JSON响应如下：

{ 
    "data": {
        "type": "person"
        "id": "1"
        "attributes": {
          "name": "Joe"
          "age": 32
          ...
        }
        "links": {
            ...
        }
    }
}

或

{ 
    "data": {
        "type": "job"
        "id": "22"
        "attributes": {
          "name": "Manager"
          "location": "Somewhere"
          ...
        }
        "links": {
            ...
        }
    }
}

他们对成功GET的Swagger定义可能如下：

   '200':
      description: OK.
      schema:
        type: object
        properties:
          data:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
              attributes:
                $ref: '#/definitions/person'

或

   '200':
      description: OK.
      schema:
        type: object
        properties:
          data:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
              attributes:
                $ref: '#/definitions/job'

在我们的Swagger文件中可能有很多重复。是否可以定义这些响应来共享公共部分？即我不想输入或复制/粘贴此部分数次：

   '200':
      description: OK.
      schema:
        type: object
        properties:
          data:
            type: object
            properties:
              id:
                type: string
              type:
                type: string

我无法使用 discriminator 字段或使用$ ref来查看这是如何工作的。

Answer 1

您可以使用allOf进行合成（与discriminator一起使用，您可以继承，但它不是真正的功能）

allOf与模式或引用数组一起使用，它将创建一个包含数组中所有定义的所有属性的新定义。

鉴于您希望某些定义能够共享id和type属性，可以这样做：

swagger: '2.0'
info:
  version: 1.0.0
  title: API

paths: {}

definitions:
  SharedDefinition:
    properties:
      id:
        type: string
      type:
        type: string

  Person:
    allOf:
      - $ref: '#/definitions/SharedDefinition'
      - properties:
          firstname:
            type: string
          lastname:
            type: string

  JobSubDefinition:
    properties:
      name:
        type: string

  Job:
    allOf:
      - $ref: '#/definitions/SharedDefinition'
      - $ref: '#/definitions/JobSubDefinition'

在这个例子中：

Person = SharedDefinition +内联定义
Job = SharedDefinition + JobSubDefinition

中的更多相关信息

Writing OpenAPI (Swagger) Specification Tutorial – Part 4 – Advanced Data Modeling（披露：我写了这个教程）
OpenAPI Specification#models-with-composition

昂首阔步的构成/继承

1 个答案: