Блог

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

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

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

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

Вот результат:

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

example Ключевое слово (не путать с multiple 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: Поддержка нескольких examples доступна в пользовательском интерфейсе Swagger 3.23.0 и редакторе Swagger 3.6.31 .