Селектор загрузки файлов в маршрутах Flasgger POST

Question

В Flasgger я пытаюсь создать документацию для маршрута, которая принимает загруженные файлы. Однако, несмотря на соблюдение спецификации, я не могу отобразить селектор файлов в интерфейсе Flasgger.

Я использую последние (на сегодня) flasgger==0.9.1 запуск спецификации OpenAPI 3 (как в "openapi": '3.0.0'), и я видел этот коммит в Swagger-UI, который включает селекторы файлов для запросов файлов POST.

Я знаю, что подобные вопросы задавались ранее, но ни один из них не касался версии 3 ОАГ.

Мой фрагмент кода ниже:

Upload a file
Returns ID of uploaded file
---

tags:
- name: "attachments"
schemes:
- "http"

consumes:
- application/octet-stream
produces:
- application/json

requestBody:
  content:
    application/octet-stream:
      schema:
        type: file
        format: binary

responses:
  200:
    ... etc

И я получаю только пустой блок ввода в Flasgger UI. Возможно ли, что Flasgger не поддерживает его, хотя Swagger-UI поддерживает (я думал, что он построен поверх него)? Или синтаксис неправильный?

Answer 1

Вы смешиваете синтаксис OpenAPI 2.0 и 3.0. В OAS3 файлы описываются как двоичные строки, то есть type: string и не type: file, Так же consumes, produces а также schemes ключевые слова не используются в OAS3.

Попробуйте следующее:

Upload a file
Returns ID of uploaded file
---

tags:
- attachments

requestBody:
  content:
    application/octet-stream:
      schema:
        type: string   # <-------
        format: binary

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          # ... etc

Обратите внимание, что для загрузки файла OAS3 требуется Swager UI 3.16.0+, но Flassger 0.9.1 связан с UI 3.14.2 и, похоже, нет способа обновить связанный Swagger UI. Эта возможность будет добавлена ​​в следующем обновлении, Flassger 0.9.2:

https://github.com/rochacbruno/flasgger

Так что вам нужно подождать Flassger 0.9.2.

Я также рекомендую проверить сгенерированный файл OpenAPI на наличие синтаксических ошибок с помощью редактора Swagger, поскольку синтаксические ошибки могут вызвать неправильный синтаксический анализ / рендеринг. В этом ответе объясняется, как экспортировать файл OpenAPI из интерфейса Swagger, чтобы вы могли использовать его в другом месте.