在开发 .NET Web API 项目时，API 文档的清晰性和可读性对前后端协作至关重要。Swagger（现称为 OpenAPI）是一个强大的工具，能自动生成交互式 API 文档，帮助开发者快速理解接口用法。本文将详细介绍如何在 .NET Web API 中集成并配置 Swagger，实现自动化文档生成。
1. 安装 Swagger 包（Swashbuckle.AspNetCore）
要在 .NET 6 或 .NET 7+ 的 Web API 项目中启用 Swagger，首先需要安装 Swashbuckle.AspNetCore 包。该包是目前最常用的 Swagger 集成方案。
通过 NuGet 包管理器或命令行安装：
dotnet add package Swashbuckle.AspNetCore安装完成后，即可在项目中配置 Swagger 中间件。
2. 配置 Swagger 服务和中间件
在 Program.cs 文件中注册 Swagger 服务，并添加对应的中间件。
示例代码如下：
var builder = WebApplication.CreateBuilder(args); // 添加 Swagger 服务 builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); var app = builder.Build(); // 启用 Swagger 中间件 if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); c.RoutePrefix = "api/docs"; // 自定义访问路径，如 /api/docs }); } app.UseHttpsRedirection(); app.MapControllers(); app.Run();说明：
AddEndpointsApiExplorer()：用于收集 API 元数据。 AddSwaggerGen()：生成 OpenAPI 文档。 UseSwagger()：启用 Swagger JSON 端点（如 /swagger/v1/swagger.json）。 UseSwaggerUI()：提供可视化界面，默认路径为 /swagger。3. 添加控制器和 Action 的注释文档
为了让 Swagger 显示更详细的说明，建议为控制器和方法添加 XML 注释。这些注释会自动显示在 Swagger UI 中。
步骤如下：
-
在 .csproj 文件中启用 XML 文档生成：
-
在 AddSwaggerGen 中指定 XML 文件路径：
-
为控制器或方法添加 XML 注释，例如：
这样，Swagger UI 就会显示摘要、返回值说明和响应状态码。
4. 自定义 Swagger 配置（可选）
你可以进一步优化 Swagger 的展示效果：
更改标题和版本： c.SwaggerDoc("v1", new OpenApiInfo { Title = "用户管理 API", Version = "v1", Description = "用于管理用户信息的 RESTful 接口" }); 添加 JWT 认证支持： c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme { In = ParameterLocation.Header, Description = "请输入 JWT token", Name = "Authorization", Type = SecuritySchemeType.Http, Scheme = "bearer" }); c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" } }, new string[] {} } });配置后，Swagger UI 会提供 “Authorize” 按钮，方便测试带 Token 的接口。
基本上就这些。只要完成上述步骤，你的 .NET Web API 就拥有了一个功能完整、界面友好的 API 文档系统。Swagger 不仅提升了开发效率，也降低了沟通成本。不复杂但容易忽略的是 XML 注释和路径配置，建议每个项目都标准化启用。
