swagger - 如何在 Swagger (OpenAPI) 中发布文件？

Question

我正在使用 Swagger 来记录我的 REST 服务。我的一项服务需要上传 CSV 文件。parameters我在 JSON API 定义的部分中添加了以下内容：

{
       "name": "File",
       "description": "The file in zip format.",
       "paramType": "body",
       "required": true,
       "allowMultiple": false,
       "dataType": "file"
}

现在我在 Swagger UI 页面上看到了文件上传选项。但是当我选择一个文件并单击“试用”时，我收到以下错误：

NS_ERROR_XPC_BAD_OP_ON_WN_PROTO：对 jquery-1.8.0.min.js 中 WrappedNative 原型对象的非法操作（第 2 行）

该页面正在不断处理，我没有得到任何回应。

有什么想法可能是错的吗？

Answer 1

OpenAPI 规范 2.0

在 Swagger 2.0 ( OpenAPI Specification 2.0 ) 中，使用设置为file的表单参数 ( in: formData) 。此外，操作必须是.typeconsumesmultipart/form-data

  consumes:
    - multipart/form-data
  parameters:
    - name: file
      in: formData   # <-----
      description: The uploaded file data
      required: true
      type: file     # <-----

OpenAPI 规范 3.0

在OpenAPI 规范 3.0中，文件被定义为二进制字符串，即type: string+ format: binary（或format: byte，取决于用例）。文件输入/输出内容的描述与任何其他模式类型的语义相同（与 OpenAPI 2.0 不同）：

多部分请求，单个文件：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # 'file' will be the field name in this multipart request
          file:
            type: string
            format: binary

多部分请求，文件数组（在 Swagger UI 3.26.0+ 和 Swagger Editor 3.10.0+ 中支持）：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items:
              type: string
              format: binary

直接 POST/PUT 文件（请求正文是文件内容）：

requestBody:
  content:
    application/octet-stream:
      # any media type is accepted, functionally equivalent to `*/*`
      schema:
        # a binary file of any type
        type: string
        format: binary

注意：语义与其他 OpenAPI 3.0 模式类型相同：

# content transferred in binary (octet-stream):
schema:
  type: string
  format: binary

更多信息：

• 文件上传的注意事项
• 多部分内容的特殊注意事项
• 文件上传和多部分请求

Answer 2

最后我找到了答案，实际上以前不支持文件上传，现在他们更新了swagger-ui.js文件。您需要用新的替换旧的，还必须在参数下为特定参数定义这些属性：

 "paramType": "body",
 "dataType": "file",

Answer 3

我的似乎与

 "paramType": "formData",
 "dataType": "file",

Answer 4

我正在使用 Open API v 3.0.3

这是我的 swagger.json 的样子：

"/media/upload": {
      "post": {
        "tags": ["Media"],
        "name": "Upload Media",
        "description": "Uploads a Media file to the server.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "media": {
                    "type": "string",
                    "format": "base64"
                  }
                }
              }
            }
          }
        }
      }
    }

以下是它大摇大摆的表现：