Блог

Как определить список файлов в Swagger?

Вот что я сделал, но это не работает.

OpenAPI 2.0

В OpenAPI 2.0 ( swagger: '2.0' ) вы должны определить каждый файл как отдельный параметр. Это означает, что вы можете описывать только запросы, которые отправляют фиксированное / ограниченное количество файлов. Невозможно определить несвязанный массив файлов.

 paths:
  /something:
    post:
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: file1
          type: file
        - in: formData
          name: file2
          type: file
        - ...
 

OpenAPI 3.0

Массивы файлов поддерживаются в OpenAPI 3.0. Запрос может быть определен следующим образом:

 openapi: 3.0.0

paths:
  /something:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                # "reports" will be used as the name of each file part/field
                # in the multipart request
                reports:
                  type: array
                  items:
                    type: string
                    format: binary
 

OpenAPI 3.1

OAS 3.1 также поддерживает файловые массивы, но синтаксис немного отличается от 3.0. В частности, items: {} вместо элементов двоичной строки используются файловые массивы.

 openapi: 3.1.0

paths:
  /something:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                # "reports" will be used as the name of each file part/field
                # in the multipart request
                reports:
                  type: array
                  items: {}