使用 yaml 对 Swagger API 描述进行“模板化”

Question

是否可以使用带有 swagger 的模板。 它是如何完成的。
我不想每次都重复 time、len 和 off 这三个属性。

看看这篇文章的结尾，我制作了一个“模板”来进行解释。

更多细节：

我有一个 JSON 响应结构，它总是返回一个始终具有相同属性的 JSON，但只有 data 的内容会发生变化。

data 可以是数组、字符串、数字、null 或对象。
这取决于 Api 的函数处理。

{
  time: "2019-02-01T12:12:324",
  off: 13,
  len: 14,
  data: [
    "Last item in the row of 14 items :-)"
  ]
}

请参阅本文末尾的 Swagger 定义示例。 它是一个yaml，可以粘贴到https://editor.swagger.io/的swagger编辑器中

在 swagger 文档 (yaml) 中，我不想重复静态重复出现的项目，这不会改变任何其他请求的功能。

如果问题不够准确，请告诉我。

swagger: "2.0"
info:
  description: ""
  version: 1.0.0
  title: "Templating?"
  contact:
    email: "someone@somewhere.com"

host: localhost
basePath: /api

paths:

  /items:
    get:
      summary: "list of items"
      produces:
        - application/json
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Items"

  /item/{id}:
    get:
      summary: "specific item"
      produces:
        - application/json
      parameters: 
        - name: id
          in: path
          description: "ID of the demanded item"
          required: true
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Item"

definitions:

  Items:
    type: object
    description: ""
    properties:
      time: 
        type: string
        format: date-time
        description: "date-time of the request"
      off:
        type: integer
        description: "index 0 based offset of list data"
        default: 0
      len:
        type: integer
        description: "overall amount of items returned"
        default: -1
      data:
        type: array
        items:
          $ref: "#/definitions/ListingItem"

  Item:
    type: object
    description: ""
    properties:
      time: 
        type: string
        format: date-time
        description: "date-time of the request"
      off:
        type: integer
        description: "index 0 based offset of list data"
        default: 0
      len:
        type: integer
        description: "overall amount of items returned"
        default: -1
      data:
        $ref: "#/definitions/InfoItem"

  ListingItem:
    type: integer
    description: "ID of the referenced item"

  InfoItem:
    type: object
    properties:
      id:
        type: string
      text:
        type: string

根据@Anthon 的回答，我想到这在某种程度上是我需要的构造。实际上它是从“模板”继承的：

...
templates:

  AbstractBasicResponse:
    properties:
      time: 
        type: string
        format: date-time
        description: "date-time of the request"
      off:
        type: integer
        description: "index 0 based offset of list data"
        default: 0
      len:
        type: integer
        description: "overall amount of items returned"
        default: -1

definitions:

  Items:
    type: object
    extends: AbstractBasicResponse
    properties:
      data:
        type: array
        items:
          $ref: "#/definitions/ListingItem"

  Item:
    type: object
    extends: AbstractBasicResponse
    properties:
      data:
        $ref: "#/definitions/InfoItem"

  ListingItem:
    type: integer
    description: "ID of the referenced item"

  InfoItem:
    type: object
    properties:
      id:
        type: string
      text:
        type: string
...

Answer 1

您可能不必恢复为完整模板，YAML 中有两件事有助于“取消加倍”重复数据：锚点/别名和合并键。

由别名 (*) 引用的 an anchor（由 & 引入）示例如下：

definitions:

  Items:
    type: object
    description: ""
    properties:
      time: 
        type: string
        format: date-time
        description: "date-time of the request"
      off: &index
        type: integer
        description: "index 0 based offset of list data"
        default: 0
      len: &amount
        type: integer
        description: "overall amount of items returned"
        default: -1
      data:
        type: array
        items:
          $ref: "#/definitions/ListingItem"

  Item:
    type: object
    description: ""
    properties:
      time: 
        type: string
        format: date-time
        description: "date-time of the request"
      off: *index
      len: *amount
  data:

YAML 解析器需要能够处理此问题，但由于别名在加载后指向同一个对象，因此在某些情况下，根据加载数据的方式，由于副作用，使用数据的代码可能不再以相同的方式工作已处理。
您可以有多个别名引用同一个锚。

merge key (<<) 是映射中的一个特殊键，您可以使用它预加载该映射与一堆键值对出现的位置。当与锚/别名一起使用时，这是最有效的。有了它，您可以进行更好的控制，您可以这样做：

  len: &altlen
    type: integer
    description: "overall amount of items returned"
    default: -1

然后

  len:
    <<: &altlen
    default: 42

然后做同样的事情：

  len:
    type: integer
    description: "overall amount of items returned"
    default: 42

合并键通常在加载时由 YAML 解析器解析，因此在使用这些键时没有潜在的副作用，即使它们涉及锚点和别名。