XML上传接口在OpenAPI 3.0中必须显式声明content-type和schema，multipart/form-data需配置encoding.file.contentType为application/xml，并提供XML example或externalDocs链接XSD以提升可读性与可验证性。
XML上传接口在OpenAPI 3.0中必须显式声明content-type和schema
OpenAPI 3.0默认倾向JSON，不写明就无法生成正确请求示例或客户端代码。XML上传本质是multipart/form-data或application/xml二选一，但语义不同：application/xml适用于纯XML体（如POST /api/v1/orders），而multipart/form-data用于带文件字段的表单（如含file字段+其他元数据）。多数“上传”场景实际走multipart，否则服务端收不到原始XML字节流。
-
application/xml：直接把XML字符串当requestBody主体，schema需用type: string+format: xml，但OpenAPI不校验XML结构 -
multipart/form-data：必须用encoding指定file字段的contentType为application/xml，否则Swagger UI会默认传text/plain - 别漏掉
required: true——OpenAPI对multipart字段默认不强制，但XML文件通常不可缺
requestBody中multipart/form-data的encoding配置容易被忽略
只写schema里的file字段类型，不配encoding，Swagger UI上传时仍会发错Content-Type。关键点在于：encoding不是可选修饰，而是multipart下控制单个字段传输行为的唯一方式。
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
metadata:
type: string
encoding:
file:
contentType: application/xml
metadata:
contentType: text/plain
-
encoding.file.contentType必须设为application/xml，不能写text/xml（虽部分服务兼容，但OpenAPI规范明确推荐application/xml） - 如果XML带中文或特殊字符，服务端需支持
UTF-8编码，但OpenAPI本身不声明字符集，靠文档或约定说明 - Swagger UI v4+ 支持该配置；旧版可能忽略
encoding，导致调试时返回415 Unsupported Media Type
如何让XML结构在文档中可见且可验证
OpenAPI 3.0不解析XML Schema（XSD），所以不能像JSON Schema那样自动展开嵌套字段。想让使用者看清XML结构，只有两个务实办法：用example给典型片段，或用externalDocs链接到XSD文件。
-
example要贴真实、最小可行的XML，包含命名空间和根元素，比如：123 - 若XML有严格XSD约束，直接在
schema里加externalDocs指向URL，比写一堆description更可靠 - 避免用
schema的xml对象（如name、namespace）——这些只影响代码生成器输出，对文档渲染无效，且多数UI工具不识别
测试时遇到400 Bad Request或415先查这三处
Swagger UI提交后报错，90%问题出在媒体类型协商失败，而非XML内容本身。
-
浏览器开发者工具Network面板里，看
Content-Type请求头是否真为multipart/form-data; boundary=...（不是application/json） - 检查
requestBody.content下是否只定义了一种mediaType，比如写了application/xml却用multipart方式传——两者互斥 - 服务端日志里确认收到的原始字节流开头是否为
，还是被转义成zuojiankuohaophpcn?xml（说明前端JS误做了HTML转义）
XML上传的复杂点不在语法，而在HTTP层的类型绑定和工具链支持程度。OpenAPI只是契约描述，它不执行解析，也不保证服务端能正确读取——你得确保Swagger定义和服务端@RequestPart（Spring）、req.files（Express）或$_FILES（PHP）的字段名、类型、编码完全对齐。
