如何为XML上传接口编写OpenAPI (Swagger) 3.0规范-XML/RSS教程

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文件。