Swashbuckle.AspNetCore中<example>标签不生效问题排查

数据老陈

2026-8-13

Swashbuckle.AspNetCore 6.4.0 标签不显示示例的排查方案

1. 先确认XML注释文件生成&加载是否到位

光在csproj里加<GenerateDocumentationFile>true</GenerateDocumentationFile>还不够，得明确XML文件的生成路径，避免文件生成位置异常导致Swagger找不到：
```
<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\YourProjectName.xml</DocumentationFile>
```

Program.cs里的SwaggerGen配置必须加上includeControllerXmlComments: true，否则控制器和方法的注释不会被加载：

builder.Services.AddSwaggerGen(c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});

2. 检查标签的写法和位置

DTO属性示例：必须把<example>直接写在属性的XML注释里，不能放到类注释中，比如：

public class UserDto
{
    /// <summary>
    /// 用户ID
    /// </summary>
    /// <example>1001</example>
    public int Id { get; set; }

    /// <summary>
    /// 用户名
    /// </summary>
    /// <example>张三</example>
    public string Name { get; set; }
}

接口响应示例：6.4.0原生对响应示例的支持有限，如果要给响应加示例，除了在方法注释里写<example>，还可以安装Swashbuckle.AspNetCore.Filters包，用[SwaggerResponseExample]属性指定示例类，比原生标签更稳定。

3. 确保Swagger UI配置没隐藏示例

检查Program.cs里的SwaggerUI配置，保证模型能展开显示示例：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API V1");
    c.DefaultModelExpandDepth(2); // 至少设为2，才能展开DTO看到属性示例
    c.DefaultModelRendering(ModelRendering.Model);
});