C# Swagger UI自定义方法 C#如何为API文档添加说明和示例

Swagger ui方法无说明需用/// 和添加xml注释，启用GenerateDocumentationFile并调用IncludeXmlComments；请求体示例推荐实现IExamplesProvider接口；响应示例须用ProducesResponseType(typeof(T))显式指定类型。

Swagger UI里方法没说明？用[Summary]和[Remarks]补上

Swagger UI默认只显示方法名和参数名，不展示业务含义。C#中需在控制器方法或参数上加XML注释，并启用Swagger的XML文档解析。

关键点：注释必须是///格式，且项目要生成XML文件（在.csproj里设true），再在Program.cs中调用AddSwaggerGen时用c.IncludeXmlComments加载。

• 类/方法顶部的///
  
  xxx

  → 显示为接口标题下方的简短说明

• /// xxx → 在“Description”区域显示补充信息，支持换行和简单html（如

  ）

• 参数用/// 用户ID，必须大于0 → 对应显示在Parameters表格的Description列

想让请求体带示例jsON？给DTO加[SwaggerSchema]或[SwaggerRequestExample]

默认情况下，Swagger对POST/PUT的body只显示字段名和类型，没有结构化示例。原生Swashbuckle不直接支持请求体示例，需引入Swashbuckle.AspNetCore.Filters包并注册过滤器。

更轻量的做法是用[SwaggerSchema(Example = @"{""name"":""test""}")]直接写死示例字符串（仅适用于简单类型），但对复杂对象容易出错；推荐方式是实现IExamplesProvider接口，返回强类型的YourDto实例，Swagger会自动序列化为json示例。

• 必须在AddSwaggerGen后调用c.ExampleFilters()
• 控制器方法上加[SwaggerRequestExample(typeof(YourDto), typeof(YourDtoExampleProvider))]
• 示例提供者里返回new YourDto { Name = “demo”, Age = 25 }，比硬编码JSON字符串更安全、可测试

响应示例不显示？检查[ProducesResponseType]是否带Type和Description

Swagger不会自动推断Task的返回内容。如果只写[ProducesResponseType(StatusCodes.Status200OK)]，UI里Response部分就只显示“200 OK”，没有模型结构和示例。

必须显式指定返回类型：

• [ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)] → 让Swagger识别响应模型
• 配合[SwaggerResponseExample]（同请求示例逻辑）可定制200/400/500等不同状态码的返回示例
• 若方法可能返回多种类型（如Ok()或NotFound()），每个[ProducesResponseType]都要单独标注，否则对应状态码的响应区域为空

中文乱码、特殊字符不渲染？XML注释里别用未转义的和>

XML注释被当作xml解析，如果

里写了if (x ，会导致XML加载失败，整个注释丢失——Swagger UI里就彻底看不到说明了，且无任何错误提示。

解决方案只有两个：

• 用zuojiankuohaophpcn代替，youjiankuohaophpcn代替>（注意是&不是&）
• 或者把整段代码块包在...标签里，它会自动转义（但仅限标签内）

这个坑特别隐蔽：编译不报错，运行时Swagger也不报错，只是静默丢弃注释。一旦发现说明消失，第一反应该查XML注释里的尖括号。