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

问题描述 投票:45回答:3

我使用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行)

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

什么想法可能是错的?

swagger swagger-ui openapi
3个回答
39
投票

OpenAPI规范2.0

在Swagger 2.0(OpenAPI Specification 2.0)中,使用表单参数(in: formData)并将type设置为file。此外,该操作的consumes必须是multipart/form-dataapplication/x-www-form-urlencoded或两者。

  consumes:
    - multipart/form-data  # and/or application/x-www-form-urlencoded
  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

多部分请求,文件数组:

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

更多的信息:


18
投票

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

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

4
投票

我似乎合作

 "paramType": "formData",
 "dataType": "file",
© www.soinside.com 2019 - 2024. All rights reserved.