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

Question

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

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

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

服务器端点是使用HTML 表单规范中的 XQRS RestXQ 上传文件来实现的。

我正在尝试为 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 或更高版本。早期版本不支持多文件上传。