Swashbuckle示例XML类型标记显示异常，求正确配置方法

问题现状 #

Swashbuckle/Swagger GUI展示的XML请求示例未遵循代码中的XML序列化注解配置，具体如下：

当前错误输出 #

<?xml version="1.0"?>
<SomesModel>
 <_Somes>
   <_SomeID>string</_SomeID>
   <_SomeName>string</_SomeName>
   <_SomeBool>true</_SomeBool>
 </_Somes>
</SomesModel>

预期输出 #

<?xml version="1.0"?>
<Somes>
  <Some>
    <SomeID>string</SomeID>
    <SomeName>string</SomeName>
    <SomeBool>true</SomeBool>
  </Some>
 <Some>
   <SomeID>string</SomeID>
   <SomeName>string</SomeName>
   <SomeBool>true</SomeBool>
 </Some>
</Somes>

现有代码配置 #

1. WebApiConfig

config.Formatters.XmlFormatter.UseXmlSerializer = True
SwaggerConfig.Register(config)

2. 控制器代码

<HttpPost>
Public Function PostGeneric(some As SomesModel) As HttpResponseMessage
    Return New HttpResponseMessage(Net.HttpStatusCode.Accepted)
End Function

3. 根对象类

<Serializable()>
<XmlRoot(ElementName:="Somes", [Namespace]:="")>
<XmlType("Somes")>
Public Class SomesModel
 <XmlElement(ElementName:="Some")>
 Public Property Somes As List(Of SomeModel)
End Class

4. 子对象类

<Serializable()>
<XmlType("Some")>
Public Class SomeModel
 <XmlElement>
 Public Property SomeID As String
 <XmlElement>
 Public Property SomeName As String
 <XmlElement>
 Public Property SomeBool As Boolean
End Class

解决配置步骤 #

Swashbuckle默认不会自动使用XmlSerializer生成XML示例，需显式配置让其尊重你的XML注解：

1. 修改SwaggerConfig配置 #

在SwaggerConfig.Register方法中，添加UseXmlSerializer()配置，强制Swashbuckle使用.NET原生XmlSerializer生成XML示例：

GlobalConfiguration.Configuration
    .EnableSwagger(Function(c)
        ' 保留原有配置，添加以下行
        c.UseXmlSerializer()
        
        ' 可选：若需读取项目XML注释文件，先在项目生成设置中启用XML文档输出，再添加
        ' c.IncludeXmlComments(HostingEnvironment.MapPath("~/App_Data/YourProjectName.xml"))
    End Function)
    .EnableSwaggerUi(Function(c)
        ' 保留原有UI配置
    End Function)

2. 验证模型序列化正确性 #

先单独测试模型的XmlSerializer序列化结果，排除模型注解本身的问题：

Dim testModel As New SomesModel()
testModel.Somes = New List(Of SomeModel) From {
    New SomeModel() With {.SomeID = "1", .SomeName = "Test1", .SomeBool = True},
    New SomeModel() With {.SomeID = "2", .SomeName = "Test2", .SomeBool = False}
}

Dim serializer As New XmlSerializer(GetType(SomesModel))
Using writer As New StringWriter()
    serializer.Serialize(writer, testModel)
    Dim outputXml = writer.ToString()
    ' 检查outputXml是否与预期结构一致
End Using

3. 修正注解细节（若需） #

如果测试发现模型序列化结果仍不符合预期，检查：

• 根类XmlRoot的ElementName是否正确设置为"Somes"
• 根类中Somes属性的XmlElement注解ElementName是否为"Some"（确保列表项生成<Some>标签）
• 子类的属性是否无需额外前缀，当前注解已正确

核心原因 #

Swashbuckle默认依赖Json.NET的模型逻辑生成示例，不会自动识别XmlSerializer的注解。只有显式启用UseXmlSerializer()后，它才会调用.NET原生XmlSerializer来生成符合你配置的XML结构。

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