Swagger 中的文件数组

Question

如何在 Swagger 中定义文件列表？

这是我所做的，但它不起作用。

Answer 1

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 中是 supported。请求可以定义如下：

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: {}