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

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

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

现在我在我的 Swagger UI 页面上看到了文件上传选项。但是，当我选择一个文件并单击“ try it out”时，会得到以下错误:

NS _ ERROR _ XPC _ BAD _ OP _ ON _ WN _ PROTO: 在 jquery-1.8.0. min.js (第2行)中对 WrappedNational 原型对象的非法操作

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

知道哪里出了问题吗？

117513 次浏览
小开

最后我找到了这个问题的答案，实际上以前没有对 档案上载的支持，现在他们更新了 斯瓦格-UI. js 斯瓦格-ui. js 斯瓦格-ui. js 斯瓦格-ui. js 斯瓦格-ui. js 斯瓦格-ui. js 文件。您需要用 new 替换旧的，并且您还必须在特定参数的“参数”下定义这些属性:

 "paramType": "body",
"dataType": "file",
小开

我的好像能用

 "paramType": "formData",
"dataType": "file",
小开
最佳答案

OpenAPI 规范2.0

在 Swagger 2.0(OpenAPI 规范2.0)中，使用表单参数(in: formData) ，将 type设置为 文件。此外，操作的 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

进一步资料:

小开

我使用的是 Open API v3.0.3

这就是我的招摇过市 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"
}
}
}
}
}
}
}
}

以下是它们如何大摇大摆地出现在人们面前的:

enter image description here


提交答案