OpenAPI 3.0 中 XML 文件上传需用 multipart/form-data，file 字段 type: string + format: binary；不可用 format: xml，否则 Swagger UI 渲染为文本框；XML 结构约束须写在 description 中，不支持 Schema 级校验。
XML上传接口在 OpenAPI 3.0 中怎么写 requestBody
OpenAPI 3.0 不支持直接用 application/xml + multipart/form-data 混合声明，必须明确区分：文件上传走 multipart/form-data，而 XML 内容体（非文件）才用 application/xml。上传 XML 文件时，本质是二进制文件提交，不是纯 XML 文本 POST。
关键点：requestBody 的 content 必须指定 multipart/form-data，且每个 part 要用 schema 描述其结构，XML 文件对应 part 的 schema 类型应为 string + format: binary（不是 xml）。
-
name字段名（如file）需与后端实际解析的 form key 一致 - 不要给该 part 设置
contentEncoding或试图声明application/xml—— multipart 的每个 part 自带Content-Type头，但 OpenAPI 不在此处校验它 - 若需约束上传文件名或扩展名，只能靠
description或自定义x-xxx扩展字段说明，OpenAPI 标准不提供校验能力
Swagger UI 能否正确渲染 XML 文件上传表单
可以，但有前提：使用 format: binary 且 type: string 定义文件字段，Swagger UI（v3.x / Swagger Editor / Redoc）才会显示「Choose File」按钮；若误写成 type: string, format: xml，它会渲染成文本输入框，导致前端无法选文件。
常见错误示例（❌）：
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: xml # 错！这不会触发文件选择器
正确写法（✅）：
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary # 关键！告诉 UI 这是文件输入
filename:
type: string
example: "order_2024.xml"
如何描述 XML 文件内容结构（比如要求特定根节点）
OpenAPI 本身不校验上传文件的内容格式，format: binary 只表示“字节流”，不等于“可解析的 XML”。如果业务上强依赖 XML 结构（例如必须含
- 在
description字段中明确写清约束，例如："XML 文件必须以开头，编码为 UTF-8" - 在
responses.400.content.application/json.schema中定义具体报错字段（如error.code = "INVALID_XML_STRUCTURE"），让调用方知道失败原因 - 后端做实际 XML 解析和 Schema/XSD 校验 —— OpenAPI 文档只负责“接口契约”，不替代业务校验
要不要加 encoding 或 headers 配置
一般不用。OpenAPI 的 encoding 是为非 multipart 场景设计的（如 JSON body 中嵌 base64 字符串），对 multipart/form-data 的每个 part，encoding 不生效。同理，headers 在 requestBody 下无意义 —— multipart 请求头（如 Content-Type: multipart/form-data; boundary=xxx）由客户端自动生成，不应由 API 文档硬性指定。
唯一需要显式提的是字符编码建议：
- 在
description中注明 “推荐 XML 声明中指定encoding="UTF-8"” - 避免在
schema层尝试用examples写带中文的 XML 片段（可能因 YAML 编码问题出错），改用外部文档链接或 base64 示例
真正容易被忽略的是：很多团队把 XML 当作普通 POST body 写成 application/xml，结果前端用 fetch 直接传字符串，既无法设 Content-Disposition，也不支持大文件分块 —— 上传 XML 文件就该走 multipart，没得绕。
