如何在 OpenAPI 中指定多文件上传？

Question

我正在尝试生成数据以填充来自我的代码库的 OpenAPI 3.0 输入。

我有一个用于将文件上传到服务器的休息端点。

我有一个表单作为用于上传文件的聚合物 vaadin 上传组件。路径为/upload-all，表单参数名称为my-attachment。表单正确地将文件上传到服务器，所以这不是问题。

服务器端点是使用 XQRS RestXQ Uploading Files in HTML Forms 规范实现的。

我正在尝试为 OpenAPI 3.0 UI 创建一个 OpenAPI JSON 输入，用于多部分文件上传。这是我尝试过的：

"/upload-all": {
    "post": {
        "consumes": ["multipart/form-data"],
        "description": "Upload zip file to the server",
        "responses": {
            "content": {
                "application/json": {
                    "schema": {
                        "type": "object"
                    }
                }
            }
        },
        "parameters": [
            {
                "in": "formData",
                "schema": {
                    "type": "array",
                    "items": {
                        "type": "file"
                    }
                },
                "name": "my-attachment"
            }
        ]
    }
},

我收到一个错误消息，表示未填充表单参数 my-attachment。我错过了什么？我无法在 OpenAPI 网站上找到明确的规范。

更新：我尝试将代码的输出更改为：

"/upload-all": {
    "post": {
        "requestBody": {
            "content": {
                "multipart/form-data": {
                    "schema": {
                        "properties": {
                            "my-attachment": {
                                "type": "array",
                                "items": {
                                    "format": "binary",
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "description": "Upload zip file to the server",
        "responses": {
            "content": {
                "application/json": {
                    "schema": {
                        "type": "object"
                    }
                }
            }
        }
    }
},

OpenAPI UI 显示如下：

应该是这样的：

OpenAPI UI 是最新的。这里缺少什么？

Answer 1

您快完成了 - 只需将 "type": "object" 添加到您的请求正文架构中：

        "requestBody": {
            "content": {
                "multipart/form-data": {
                    "schema": {
                        "type": "object",   // <-------
                        "properties": {
                            "my-attachment": {
                                ...

确保您使用的是 Swagger UI v. 3.25.3 或更高版本。早期版本 did not support 多文件上传。

如何在 OpenAPI 中指定多文件上传？

How do I specify a multifile upload in OpenAPI?

json

file-upload

multipartform-data

swagger

openapi