Swagger UI方法无说明需用/// 和添加XML注释，启用GenerateDocumentationFile并调用IncludeXmlComments；请求体示例推荐实现IExamplesProvider接口；响应示例须用ProducesResponseType(typeof(T))显式指定类型。
Swagger UI里方法没说明？用[Summary]和[Remarks]补上
Swagger UI默认只显示方法名和参数名，不展示业务含义。C#中需在控制器方法或参数上加XML注释，并启用Swagger的XML文档解析。
关键点：注释必须是///格式，且项目要生成XML文件（在.csproj里设<generatedocumentationfile>true</generatedocumentationfile>），再在Program.cs中调用AddSwaggerGen时用c.IncludeXmlComments加载。
- 类/方法顶部的
/// <summary>xxx</summary>→ 显示为接口标题下方的简短说明 -
/// <remarks>xxx</remarks>→ 在“Description”区域显示补充信息，支持换行和简单HTML（如<p><b></b></p>） - 参数用
/// <param name="id">用户ID，必须大于0→ 对应显示在Parameters表格的Description列
想让请求体带示例JSON？给DTO加[SwaggerSchema]或[SwaggerRequestExample]
默认情况下，Swagger对POST/PUT的body只显示字段名和类型，没有结构化示例。原生Swashbuckle不直接支持请求体示例，需引入Swashbuckle.AspNetCore.Filters包并注册过滤器。
更轻量的做法是用[SwaggerSchema(Example = @"{""name"":""test""}")]直接写死示例字符串（仅适用于简单类型），但对复杂对象容易出错；推荐方式是实现IExamplesProvider<yourdto></yourdto>接口，返回强类型的YourDto实例，Swagger会自动序列化为JSON示例。
- 必须在
AddSwaggerGen后调用c.ExampleFilters() - 控制器方法上加
[SwaggerRequestExample(typeof(YourDto), typeof(YourDtoExampleProvider))] - 示例提供者里返回new YourDto { Name = "demo", Age = 25 }，比硬编码JSON字符串更安全、可测试
响应示例不显示？检查[ProducesResponseType]是否带Type和Description
Swagger不会自动推断Task<iactionresult></iactionresult>的返回内容。如果只写[ProducesResponseType(StatusCodes.Status200OK)]，UI里Response部分就只显示“200 OK”，没有模型结构和示例。
必须显式指定返回类型：
-
[ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]→ 让Swagger识别响应模型 - 配合
[SwaggerResponseExample]（同请求示例逻辑）可定制200/400/500等不同状态码的返回示例 - 若方法可能返回多种类型（如
Ok()或NotFound()），每个[ProducesResponseType]都要单独标注，否则对应状态码的响应区域为空
中文乱码、特殊字符不渲染？XML注释里别用未转义的和<code>>
XML注释被当作XML解析，如果<summary></summary>里写了if (x ，会导致XML加载失败，整个注释丢失——Swagger UI里就彻底看不到说明了，且无任何错误提示。
解决方案只有两个：
- 用
<代替，<code>>代替>（注意是&不是&） - 或者把整段代码块包在
<code>...标签里，它会自动转义（但仅限<code>标签内）
这个坑特别隐蔽：编译不报错，运行时Swagger也不报错，只是静默丢弃注释。一旦发现说明消失，第一反应该查XML注释里的尖括号。
