Блог

У меня есть следующие спецификации:

 ---
openapi: 3.0.0
info:
  title: Players API
  version: 0.0.1-alpha1

paths:
  /players/{id}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PlayerWrapper'
components:
  schemas:
    PlayerWrapper:
      type: object
      properties:
        display_name:
          type: string
          example: 76ers
        config:
          description: |
            The configuration of the player.
          example: { spec: { team: 76ers, names: [ 1, 2 ] } }
          allOf:
            - $ref: '#/components/schemas/Player'
    Player:
      type: object
      properties:
        spec:
          allOf:
            - $ref: '#/components/schemas/BasicPlayer'
      additionalProperties: false
    BasicPlayer:
      type: object
      properties:
        team:
          type: string
        names:
          allOf:
            - $ref: '#/components/schemas/Names'
      additionalProperties: false
    Names:
      type: array
      items:
        type: string
      example: [ Ben, Joel ]
 

Я действительно проверил на Суэггере, что он действительно действителен. Вопрос в том, почему я могу видеть names: [ 1, 2 ] иначе, чем [ Ben, Joel ] . Когда я удаляю эту example вещь ( # example: { spec: { team: 76ers, names: [ 1, 2 ] } } ), я могу увидеть Ben, Joel пример:

Есть ли способ, как я могу принудительно переопределить / объединить эти примеры? На данный момент я чувствую, что мой пример переопределяется любым из этих полей (т. Е. Либо 76ers / [1, 2], либо строкой / [Бен, Джоэл], но вместо этого я хотел бы получить 76ers / [Бен, Джоэл]).

Структура в ваших схемах не совсем верна. Идея заключается в том, чтобы предоставить примеры простых типов (строки, int и т. Д.), И схема структурирует их по мере необходимости.

Поэтому не помещайте пример в конфигурацию, поместите его во вложенные простые типы, подобные этому, т. Е. BasicPlayer объект должен иметь example команду «включено», так как это строка:

     BasicPlayer:
      type: object
      properties:
        team:
          type: string
          example: '76ers'
        names:
          allOf:
            - $ref: '#/components/schemas/Names'
 

Аналогично с PlayerWrapper.config не пытайтесь дать полный объект в примере, он составляется из свойств элемента. Таким team образом, получается пример, но Names пример составлен из дочернего типа.

     PlayerWrapper:
      type: object
      properties:
        display_name:
          type: string
          example: '76ers'
        config:
          description: |
            The configuration of the player.
          allOf:
            - $ref: '#/components/schemas/Player'
 

Что должно дать вам ожидаемый пример:

Вот вам и вся развязность:

 ---
openapi: 3.0.0
info:
  title: Players API
  version: 0.0.1-alpha1

paths:
  /players/{id}:
    get:
      parameters: 
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PlayerWrapper'
components:
  parameters:
    id: 
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The id.
  schemas:
    PlayerWrapper:
      type: object
      properties:
        display_name:
          type: string
          example: '76ers'
        config:
          description: |
            The configuration of the player.
          allOf:
            - $ref: '#/components/schemas/Player'
    Player:
      type: object
      properties:
        spec:
          allOf:
            - $ref: '#/components/schemas/BasicPlayer'
      additionalProperties: false
    BasicPlayer:
      type: object
      properties:
        team:
          type: string
          example: '76ers'
        names:
          allOf:
            - $ref: '#/components/schemas/Names'
      additionalProperties: false
    Names:
      type: array
      items:
        type: string
        example: 
          - Ben
          - Joel
 

Примечание. Примеры схем можно переопределить с помощью примера в определении ресурса, например:

 paths:
  /players/{id}:
    get:
      parameters: 
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PlayerWrapper'
              example:
                display_name: 76ers
                config:
                  spec:
                    team: 76ers
                    names:
                      - 'Ben'
                      - 'Joel'