Question

是否可以使用带有wagger的模板。怎么做
我不想每次都重复 time ， len 和 off 这三个属性。

看看这篇文章的末尾，我在其中构建了一个用于解释的“模板”。

更多详细信息：

我有一个JSON响应结构，该结构总是返回一个始终具有相同属性的JSON，但是只有 data 的内容可以更改。

数据可以是数组，可以是字符串，数字，空值或对象。
这取决于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编辑器中

在不拘一格的文档（ 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解析器解析，因此，使用合并键时，即使它们涉及锚和别名，也没有潜在的副作用。

使用yaml对Swagger API说明进行“模板化”

1 个答案: