.NET Core 5 WebAPI中XML序列化器与Swagger示例生成结构不一致问题排查

必须对Swagger开展专项配置才能实现序列化规则统一，不存在开箱即用的兼容方案。
.NET Core生态下默认集成的Swashbuckle组件，其XML结构推导逻辑和WebAPI管道中通过AddXmlSerializerFormatters注册的原生XmlSerializer规则完全独立，不会自动对齐服务端的实际序列化行为。

• 服务端接收到POST请求时，会严格按照模型上标注的System.Xml.Serialization命名空间下的XML特性做反序列化：针对继承自List<Item>的自定义Items集合类，你标注的节点层级规则（<Items>作为根集合节点，内部嵌套多个独立<Item>子节点）会被原生XmlSerializer完整识别，手动序列化测试对象时也能输出符合预期的XML结构
• Swagger默认生成XML示例时，采用内置的类型结构推导逻辑，优先识别DataContract相关特性，对XmlSerializer专属特性的支持存在缺失：遇到自定义集合类时，会默认触发集合平铺逻辑，跳过你定义的集合嵌套层级规则，最终生成的示例会缺失Item节点的嵌套结构，和服务端实际可接收的格式产生偏差
• 你配置的System.Text.Json序列化规则（保留原属性名大小写、添加枚举字符串转换器）仅作用于JSON序列化管线，和XML序列化流程、Swagger示例生成逻辑完全解耦，不会影响Swagger的XML示例输出效果

• 替换Swagger默认的XML示例生成逻辑：自定义实现IXmlExampleGenerator接口，在生成请求/响应示例时，直接复用项目中已配置的XmlSerializer实例，按照原生序列化规则将示例对象转换为标准XML字符串
• 适配自定义集合类的结构规则：在自定义生成逻辑中，严格按照模型上标注的XmlSerializer特性解析节点层级，跳过Swagger默认的集合平铺推导，确保生成的XML结构和原生序列化输出完全一致
• 完成逻辑开发后，在AddSwaggerGen的服务注册流程中，通过配置项将默认的XML示例生成器替换为自定义实现
• 上线前需交叉校验生成的XML示例：核对节点层级、属性名大小写、枚举值展示格式，确保和服务端实际可接收的XML规则完全匹配

内容的提问来源于stack exchange，提问作者Jeremy