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

Question

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

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

更多详情:

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

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

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

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

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

如果问题不够准确，请让我知道。

swagger: "2.0"
info:
  description: ""
  version: 1.0.0
  title: "Templating?"
  contact:
    email: "[e-mail]"

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

根据@Anthony的回答，我想这是我需要的结构。实际上它继承自“模板”：

...
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中有两件事有助于“取消发布”重复数据：锚/别名和合并键。

锚的示例（由＜code＞介绍）

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解析器需要能够处理这一点，但是由于加载后别名指向同一个对象，使用数据的代码可能不再工作，因为在某些情况下会产生副作用，这取决于加载数据的处理方式。< br >同一锚点可以有多个别名。

合并键（

  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解析器解析，因此在使用它们时没有潜在的副作用，即使它们涉及锚和别名。