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

Posted 2023-02-16

【中文标题】如何在 Swagger (OpenAPI) 中发布文件？

【英文标题】：How to post files in Swagger (OpenAPI)?

【发布时间】：2013-01-05 11:56:29

【问题描述】：

我正在使用 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 中 WrappedNative 原型对象的非法操作（第 2 行）

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

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

【问题讨论】：

“file”后面不加最后一个逗号可以试试吗？

@Soc : 请忽略那个逗号，这只是一个拼写错误。

也许您可以尝试通过以下方式进行调试：（也许使用更新的查询版本），使用非最小化版本的 jquery 并查看 JS 控制台（也许设置断点）并找到找出错误是如何产生的。也许您会获得更多有关导致问题的原因的信息。

【参考方案1】：

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

它是这样大摇大摆的：

【讨论】：

您是否从 aws api 网关开发人员门户中截取了上面的屏幕截图。即使我创建了类似的rest api，我也没有选择文件的选项。

这是来自我的本地机器

【参考方案2】：

OpenAPI 规范 2.0

在 Swagger 2.0 (OpenAPI Specification 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 Specification 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

更多信息：

Considerations for File Uploads Special Considerations for multipart Content File Upload 和 Multipart Requests

【讨论】：

如何访问节点js控制器中的文件？比如如果我的文件名为filedata，那么我的流内变量应该初始化为req.swagger.params.filedata.value？这给了我一个错误。

您能否解释一下为什么招摇的 OpenAPI 规范没有指出这一点？ swagger.io/specification/#considerations-for-file-uploads-61

@AmazingTurtle 你链接到 OpenAPI 规范 3.0；我已更新答案以包含 OpenAPI 规范 3.0。

你能解释更多吗，例如：当我使用 Django REST 框架时，应该修改哪个代码模块？谢谢！

【参考方案3】：

我的似乎可以使用

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

【讨论】：

此答案适用于旧版本的 Swagger 规范（1.x？），不适用于 OpenAPI 2.0 / OpenAPI 3.0。请参阅mstrthealias' answer。

【参考方案4】：

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

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

【讨论】：

我怎样才能将文件与其他数据一起添加（比如带有某些字段的文件？）

@Win 你找到解决问题的方法了吗？

此答案适用于旧版本的 Swagger 规范（1.x？），不适用于 OpenAPI 2.0 / OpenAPI 3.0。请参阅mstrthealias' answer。