Swagger UI XML示例未遵循类的XML注解，如何解决？

API 探路者

2026-6-26

问题描述

现有带XML序列化注解的C#类：

[XmlRoot("MySample", Namespace = "http://mynamespace.org")]
public class Sample
{
    [XmlAttribute("version")]
    public string Version { get; set; }

    [XmlAttribute("timestamp")]
    public string TimeStamp{ get; set; }

    [XmlElement("Property1")]
    public string MyProperty { get; set; }
}

接口实际返回的XML符合注解规则：

<MySample version="1.2" timestamp="4/12/2024 5:56 PM" xmlns="http://mynamespace.org">
  <Property1>My Value</Property1>
</MySample>

但Swagger UI展示的XML示例未遵循这些规则，显示为：

<Sample>
    <Version>string</Version>
    <TimeStamp>string</TimeStamp>
    <MyProperty>string</MyProperty>
</Sample>

需让Swagger UI遵循XML序列化注解生成正确示例。

解决方案

要让Swagger UI识别System.Xml.Serialization注解并生成正确的XML示例，按以下步骤配置：

1. 生成项目XML文档

打开项目属性的生成标签页，勾选「XML文档文件」，设置输出路径为$(OutputPath)$(AssemblyName).xml。这一步是让Swagger能读取类的元数据和注解信息。

2. 配置Swagger使用XmlSerializer

在Program.cs的服务配置中，修改Swagger生成器的设置，加载XML文档并指定使用XmlSerializer：

builder.Services.AddSwaggerGen(c =>
{
    // 加载项目生成的XML注释文件
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    c.IncludeXmlComments(xmlFilePath);

    // 启用XmlSerializer支持，使其识别XmlRoot、XmlAttribute等序列化注解
    c.UseXmlSerializer();
});