Swagger повторно использует примеры, показывающие странный элемент $$ ref - PullRequest
Новая
       8

Swagger повторно использует примеры, показывающие странный элемент $$ ref

0 голосов
/ 27 марта 2019

Я написал файл спецификации Yaml Swagger и в разделе components у меня есть: 

examples:
  companyExample:
    company:
      id: uNiquEiD
      name: Company Name

Я использую это companyExample в ответе следующим образом: 

example:
  $ref: '#/components/examples/companyExample'

Вот вывод:

enter image description here

Так что же это за дополнительный "$$ref": "#/components/examples/companyExample" это ошибка?Как я могу удалить это?

1 Ответ

2 голосов
/ 27 марта 2019

Ключевое слово example (не путать с несколькими exampleS) не поддерживает $ref. Целое значение примера должно быть указано в строке: 

example:
  company:
    id: uNiquEiD
    name: Company Name


Для $ref примера, определенного в #/components/examples, вам нужно использовать ключевое слово examples. examples может использоваться в параметрах, телах запросов, телах ответов и заголовках ответов, но НЕ в схемах. Другими словами, examples может использоваться рядом с schema, но не внутри schema.

Например, для $ref примера в качестве примера ответа вы должны использовать следующее. Обратите внимание, что определение примера использует ключевое слово value для переноса фактического значения примера. (Пример определения в исходном вопросе недействителен из-за пропущенного value.) 

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
              examples:
                companyExample:
                  $ref: '#/components/examples/companyExample'

components:
  examples:
    companyExample:
      summary: Sample company data
      value:
        # The actual example value begins here
        company:
          id: uNiquEiD
          name: Company Name

Примечание для пользователей Swagger UI: Поддержка нескольких examples доступна в Swagger UI 3.23.0+ и Swagger Editor 3.6.31 +.

...