«Шаблонирование» в Swagger API Description с помощью yaml

Question

Можно ли использовать шаблоны с чванством?Как это сделать.
Я не хочу повторять три свойства время , len и off каждый раз.

Посмотрите в конце этого поста, где я составил «шаблон» для объяснения.

Подробнее:

У меня есть структура ответа JSON, которая всегда возвращаетJSON всегда с одинаковыми свойствами, но только содержимое data может быть изменено.

data может быть массивом, может быть строкой, числом, нулемили объект.
Это зависит от обработки функций 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 ( 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 есть две вещи, которые помогают «удваивать» повторяющиеся данные: якоря / псевдонимы и ключи слияния.

Пример якорь (введенный &), на который ссылается псевдоним (*), будет:

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 должен иметь возможность обрабатывать это, но поскольку псевдоним указывает на тот же объектпосле загрузки код, использующий данные, может больше не работать из-за побочного эффекта в некоторых случаях, в зависимости от того, как обрабатываются загруженные данные.
Вы можете иметь несколько псевдонимов, ссылающихся на один и тот же якорь.

ключ объединения (<<) - это специальный ключ в сопоставлении, с помощью которого вы можете предварительно загрузить это сопоставление, где оно происходит, с помощью набора пар ключ-значение.Это наиболее эффективно при использовании с якорем / псевдонимом.С этим у вас есть более тонкий контроль, и вы можете сделать:

  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, поэтому при их использовании не возникает потенциальных побочных эффектов, даже если они связаны с якорями и псевдонимами.