C#中Swagger文档生成_C#OpenAPI文档生成教程【必备】-C#.Net教程-PHP中文网

microsoft.aspnetcore.openapi是.net 9+官方内置的轻量级openapi文档生成方案，仅输出json/yaml文档、不带ui、默认openapi 3.1、支持构建时生成和aot编译；swashbuckle.aspnetcore则自带可定制swagger ui，但需严格按addcontrollers→addendpointsapiexplorer→addswaggergen顺序配置，且功能更丰富但体积大。

c#中swagger文档生成_c#openapi文档生成教程【必备】

用 Swashbuckle.AspNetCore 还是 Microsoft.AspNetCore.OpenApi，取决于你是否需要 Swagger UI —— 前者带 UI 且高度可定制，后者轻量、原生、只输出 OpenAPI 文档，不带 UI。

Swashbuckle.AspNetCore 配置必须按顺序调用 AddControllers → AddEndpointsApiExplorer → AddSwaggerGen

顺序错一个，AddSwaggerGen 就扫不到控制器路由，Swagger UI 页面空白或 404。这不是警告，是硬性依赖：ASP.NET Core 的端点发现机制靠 AddEndpointsApiExplorer 暴露路由元数据，而它必须在控制器注册之后、Swagger 注册之前执行。

AddControllers() 是基础，没它连 API 方法都不注册
AddEndpointsApiExplorer() 必须紧随其后，否则 AddSwaggerGen() 拿不到任何 ApiDescription
AddSwaggerGen() 里若漏掉 c.SwaggerDoc("v1", ...)，UI 会报 “No API definition found”
XML 注释要生效，得同时满足：项目属性勾选“XML 文档文件” + IncludeXmlComments 路径存在且可读

JWT 鉴权按钮不出现在 Swagger UI？检查 SecurityDefinition 和 UseSwaggerUI 的配对

光在 AddSwaggerGen 里加 AddSecurityDefinition("Bearer", ...) 不够，还必须在 UseSwaggerUI 中显式启用鉴权流程，否则 “Authorize” 按钮压根不会渲染。

C函数速查手册（CHM版）

下载

AddSecurityDefinition 只定义了安全方案名称和格式，不触发 UI 组件
必须配合 c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" } }, new string[0] } });
UseSwaggerUI 调用中不能省略 c.EnablePersistAuthorization()，否则登录态无法跨请求保持
如果 API 实际用的是 X-API-Key 或 Basic，别硬套 Bearer 示例，Scheme 和 In 参数必须匹配真实 Header 名和位置

生成的 openapi.json 是空的或字段缺失？优先排查 XML 注释和模型绑定方式

Swagger UI 显示正常不代表文档完整 —— openapi.json 里 components/schemas 缺失、requestBody 类型为 object、example 字段全空，八成是模型没被正确反射出来。

DTO 类必须是 public，且所有属性为 public get/set；internal 或 private set 会导致字段不出现
用 [FromBody] 但参数类型是 object 或未标注 [JsonObject]，Schema 会退化为泛型 object
XML 注释里 <summary></summary> 只影响 description，<param name="xxx"> 才能补全参数说明，漏写就留白
枚举值默认只显示数字，加 [JsonConverter(typeof(JsonStringEnumConverter))] 并启用 DescribeAllEnumsAsStrings() 才能出字符串枚举

.NET 9+ 项目别硬套 Swashbuckle，优先试 `AddOpenApi` + `MapOpenApi`

Microsoft.AspNetCore.OpenApi 是微软官方内置方案，.NET 9+ 默认集成，体积小、启动快、天然 AoT 友好，但代价是：没有 Swagger UI、不支持多文档切换、主题和按钮不可定制。

AddOpenApi() 默认输出 OpenAPI 3.1，改版本要显式传 options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0
MapOpenApi() 默认挂载到 /openapi/v1.json，加 ".yaml" 后缀可返回 YAML 格式（如 /openapi/v1.yaml）
它不读 XML 注释，也不支持 JWT 安全定义的 UI 渲染 —— 这些功能只能靠 Swashbuckle 或第三方转换器补足
如果你只是想 CI 里自动生成文档存档，或前端用 swagger-client 解析，AddOpenApi 更干净，少一堆中间件干扰

真正容易被忽略的点是：Swagger UI 的 /swagger 端点和 OpenAPI 文档的 /swagger/v1/swagger.json 是两个独立资源，前者是静态 HTML+JS，后者是纯 JSON；关掉 UI 不等于关掉文档，反过来也一样。部署时权限控制、CORS、反向代理路径重写，都得分别处理这两条路径。