如何在Swagger（OpenAPI）中发布文件？

Question

如何在Swagger（OpenAPI）中发布文件？

78

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

{
       "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（第2行）中对WrappedNative原型对象进行非法操作

页面持续处理，我没有得到任何响应。

有什么想法可能出了什么问题吗？

- CodeGuru

你能试着去掉“file”后面的逗号吗？ - Sebastian Stiehl

@Soc：请忽略那个逗号，那只是一个打字错误。 - CodeGuru

也许你可以尝试以下调试方式：（可能使用更新的查询版本），使用未经最小化的jQuery版本，并查看JS控制台（可能设置断点），找出错误是如何产生的。也许你会获得更多关于问题原因的信息。 - mr.VVoo

4个回答

19

最终我找到了这个问题的答案，实际上以前没有支持文件上传，现在他们更新了swagger-ui.js文件。您需要用新的文件替换旧的文件，并且还需要在特定参数的参数下定义这些属性：

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

- CodeGuru

3

此回答适用于较旧版本的 Swagger 规范（1.x？），在 OpenAPI 2.0 / OpenAPI 3.0 中不起作用。请参考 mstrthealias 的答案。 - Helen

4

我的似乎可以用。

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

- Artjom Kurapov

1

这个答案适用于较旧版本的Swagger规范（1.x？），在OpenAPI 2.0 / OpenAPI 3.0中不起作用。请参考mstrthealias的答案。 - Helen

3

我正在使用 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"
                  }
                }
              }
            }
          }
        }
      }
    }

下面是在Swagger中的显示方式：

- Hamza Azad

你是从AWS API Gateway开发者门户网站中截取的上述屏幕截图吗？即使我创建了类似的REST API，我也没有得到选择文件的选项。 - k''

这是来自我的本地机器。 - Hamza Azad

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- mstrthealias · Accepted Answer

OpenAPI规范2.0

在Swagger 2.0中（OpenAPI规范2.0）, 使用一个表单参数 (in: formData)，并将 type 设置为 file。此外，操作的 consumes 必须是 multipart/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

更多信息: