如何在 Swagger (OpenAPI) 中发布文件? [英] How to post files in Swagger (OpenAPI)?

问题描述

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

I am using Swagger to document my REST services. One of my services requires a CSV file to be uploaded. I added the following to the parameters section in my JSON API definition:

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

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

and now I see the file upload option on my Swagger UI page. But when I select a file and click "try it out", I get the following error:

NS_ERROR_XPC_BAD_OP_ON_WN_PROTO:对 jquery-1.8.0.min.js 中 WrappedNative 原型对象的非法操作(第 2 行)

NS_ERROR_XPC_BAD_OP_ON_WN_PROTO: Illegal operation on WrappedNative prototype object in jquery-1.8.0.min.js (line 2)

页面正在持续处理中，我没有收到任何响应.

The page is continuously processing and I am not getting any response.

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

Any ideas what could be wrong?

推荐答案

OpenAPI Specification 2.0

在 Swagger 2.0 中(OpenAPI 规范2.0)，使用表单参数 (in: formData) 并将 type 设置为 file.此外，操作的 consumes 必须是 multipart/form-data.

OpenAPI Specification 2.0

In Swagger 2.0 (OpenAPI Specification 2.0), use a form parameter (in: formData) with the type set to file. Additionally, the operation's consumes must be 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 不同):

OpenAPI Specification 3.0

In OpenAPI Specification 3.0, files are defined as binary strings, that is, type: string + format: binary (or format: byte, depending on the use case). File input/output content is described with the same semantics as any other schema type (unlike OpenAPI 2.0):

多部分请求，单个文件:

Multi-part request, single file:

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+ 中支持):

Multi-part request, array of files (supported in Swagger UI 3.26.0+ and 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文件(请求体为文件内容):

POST/PUT file directly (the request body is the file contents):

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 模式类型相同:

Note: the semantics are the same as other OpenAPI 3.0 schema types:

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

更多信息:

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

这篇关于如何在 Swagger (OpenAPI) 中发布文件?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！