Блог

Главная - Вопросы по программированию - Могу ли я добавить примеры содержимого файлов в спецификации OpenAPI?

Могу ли я добавить примеры содержимого файлов в спецификации OpenAPI?

#xml #swagger-ui #openapi

#xml #swagger-пользовательский интерфейс #openapi

Вопрос:

Мой сервис обеспечивает загрузку XML-файлов. Спецификация OpenAPI не определяет схему. Я хочу привести пример входных данных. Я пробую это:

 /foo:
    post:      
      requestBody:
        content: 
          application/xml:
            schema:
              type: string
              format: binary
              example:
                  externalValue: 'https://www.w3schools.com/xml/note.xml'

Однако swagger-ui создает бесполезный:

 <!-- XML example cannot be generated; root element name is undefined -->

Можно ли указать пример из внешнего файла?

Ответ №1:

Это зависит от того, какую версию OpenAPI вы используете.

OpenAPI 3.1

externalValue может быть любой допустимый UR I. Сюда входят относительные ссылки. Смотрите документацию 3.1.

OpenAPI 3.0

externalValue должен быть допустимый UR L. Это не может быть относительный путь к файлу. Смотрите документацию 3.0.

Измените ваше значение на размещенное местоположение вашего XML-файла.

Ошибка swagger-ui сообщает вам, что вы не используете именованный элемент. Попробуйте указать имя. (Обратите внимание, что этот инструмент содержит ошибки и некорректно поддерживает все допустимые проекты OpenAPI. Например, эта связанная ошибка.)

 examples:
  exampleName:
    summary: A sample object
    externalValue: 'https://www.w3schools.com/xml/note.xml'

Комментарии:

1. Спасибо. Я в OpenAPI 3.0. Однако, даже используя абсолютный URI (см. Обновленный вопрос), пример не включен в вывод Swagger-ui.

2. Я добавил дополнительную информацию о том, что вы можете попробовать.