Атрибут примера Swagger, скрывающий все остальные атрибуты - PullRequest
Новая
       16

Атрибут примера Swagger, скрывающий все остальные атрибуты

0 голосов
/ 31 августа 2018

Я пишу определение Swagger на swaggerhub . Есть возможность делиться моделями между несколькими Swaggers. После того, как сваггеры завершены, есть возможность загрузить решенный сваггер с импортированными связанными определениями.

Моя проблема в том, что эта разрешенная загрузка добавляет к моделям узел example, который по какой-либо причине переопределяет каждый атрибут, когда мы снова копируем этот новый Swagger в редактор.

Предположим, у нас есть следующий образец 

---
swagger: "2.0"
info:
  description: ""
  version: 1.0.0
  title: title
host: "example.com"
basePath: /
schemes:
- http
consumes:
- application/json
produces:
- application/json
paths:
  /test-service:
    post:
      tags:
      - test-service
      operationId: test-service
      parameters:
      - in: body
        name: body
        description: body
        required: true
        schema:
          $ref: '#/definitions/A'
      responses:
        201:
          description: success
          schema:
            $ref: '#/definitions/A'
definitions:
  A:
    type: object
    properties:
      a1:
        type: string
      a2:
        type: string

Ниже показано, как это отображается в Swagger UI,

Это правильный путь, однако, когда в модели есть пример узла A, в пользовательском интерфейсе отображаются только примерные атрибуты,

Correctly displayed

Вот изменение, которое я имею в виду 

  A:
    type: object
    properties:
      a1:
        type: string
      a2:
        type: string
    example:
      ex1: Hello
      ex2: World

Теперь, если я импортирую это изменение в редакторе, пропадут только атрибуты ex1 и ex2 и действительные атрибуты a1 и a2.

Incorrectly displayed

Проблема обостряется, когда мы получаем наследство.

Что происходит в зависимости от того, какой самый нижний узел в иерархии имеет example только атрибуты, перечисленные в атрибутах, которые отображаются в пользовательском интерфейсе, а не все атрибуты

Вот пример с Correctly displayed

Теперь давайте введем атрибут example в C. После добавления атрибута example на любом уровне все остальные атрибуты игнорируются.

Вот ссылка на example документацию по атрибутам https://swagger.io/docs/specification/2-0/adding-examples/.

Там нет описания этого странного поведения.

Incorrectly displayed

1 Ответ

0 голосов
/ 31 августа 2018

Вот как example работает. Цитирование спецификации OpenAPI 2.0 :

Пример произвольной формы ... экземпляра для этой схемы.

То есть example является примером для всей схемы . Вот почему уровень схемы example отображается как есть. Он переопределяет любые примеры уровня свойств и не будет автоматически включать свойства, которые не включены в example.


В последнем примере с allOf схема для A эквивалентна 

definitions:
  A:
    type: object
    properties:
      a1:
        type: string
      a2:
        type: string
      b1:
        type: string
      b2:
        type: string
      c1:
        type: string
      c2:
        type: string
    example:
      ex1: Hello
      ex2: world

, что опять же объясняет, почему уровень схемы example из C отменяет все остальное.


Вместо этого вы можете использовать примеры на уровне свойств: 

definitions:
  A:
    type: object
    properties:
      a1:
        type: string
        example: Hello   # <---
      a2:
        type: string
        example: world   # <---
...