Swagger 组合/继承 [英] Swagger composition / inheritance

问题描述

我正在尝试使用 Swagger 记录 REST API.来自我们 API 的简化 JSON 响应如下所示:

I'm trying to document a REST API using Swagger. A simplified JSON response from our API looks like:

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

或

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

他们对成功 GET 的 Swagger 定义可能如下所示:

Their Swagger definitions for a successful GET might look like:

   '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 文件中可能有很多这样的重复.是否可以定义这些响应以共享公共部分?即我不想输入或复制/粘贴这部分数十次:

There's potentially a lot of repetition like this in our Swagger file. Is it possible to define these responses to share the common parts? i.e. I don't want to type out or copy/paste this part tens of times:

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

使用 discriminator 字段或使用 $ref 时，我看不出这是如何工作的.

I couldn't see how this would work using the discriminator field, or using $ref.

推荐答案

你可以使用 allOf 来做组合(结合 discriminator 可以做继承，但不是真的很实用)

You can use allOf to do composition (in conjunction with discriminator you can do inheritance but it's not really functionnal)

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

allOf is used with an array of schema or reference, it will create a new definition containing all properties of all definitions in the array.

鉴于您希望某些定义共享 id 和 type 属性，可以通过以下方式完成:

Given that you want some of your definitions to share id and type properties, it is done this way:

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'

在这个例子中:

• 人员 = SharedDefinition + 内联定义
• 作业 = SharedDefinition + JobSubDefinition

更多关于这个在

• 编写 OpenAPI (Swagger) 规范教程– 第 4 部分 – 高级数据建模(披露:我编写了本教程)
• OpenAPI 规范#models-with-组合

• Writing OpenAPI (Swagger) Specification Tutorial – Part 4 – Advanced Data Modeling (disclosure: I wrote this tutorial)
• OpenAPI Specification#models-with-composition

这篇关于Swagger 组合/继承的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！