.NET Web API如何使用Swagger生成API文档-C#.Net教程-PHP中文网

.NET Web API如何使用Swagger生成API文档

小老鼠

发布： 2025-11-02 05:43:11

原创

490人浏览过

在 .NET Web API 中集成 Swagger 可自动生成可交互的 API 文档。首先通过 NuGet 安装 Swashbuckle.AspNetCore 包，然后在 Program.cs 中添加 AddEndpointsApiExplorer() 和 AddSwaggerGen() 服务，并使用 UseSwagger() 和 UseSwaggerUI() 启用中间件，自定义访问路径如 /api/docs。为显示 XML 注释，需在 .csproj 中启用 GenerateDocumentationFile，并在 AddSwaggerGen 中调用 IncludeXmlComments() 指定 XML 文件路径，同时在代码中使用 /// 添加 summary 等注释。还可自定义 API 信息，如设置标题、版本、描述，以及添加 JWT 认证支持，通过 AddSecurityDefinition 和 AddSecurityRequirement 配置 Bearer 鉴权。集成后无需手动维护文档，支持页面化接口测试，提升开发效率与协作体验。

.net web api如何使用swagger生成api文档

在 .NET Web API 项目中集成 Swagger，可以自动生成可视化且可交互的 API 文档，极大提升开发效率和前后端协作体验。Swagger（现称为 OpenAPI）通过分析控制器和方法的结构，自动展示接口路径、参数、返回值和示例数据。以下是具体实现步骤。

安装 Swashbuckle.AspNetCore 包

Swashbuckle 是 .NET 平台最常用的 Swagger 集成工具。你需要通过 NuGet 安装它：

在 Visual Studio 中右键项目 → “管理 NuGet 程序包” → 搜索并安装 Swashbuckle.AspNetCore
或使用 Package Manager Console 执行命令：

Install-Package Swashbuckle.AspNetCore

也可使用 .NET CLI：

dotnet add package Swashbuckle.AspNetCore

配置 Swagger 中间件

在 Program.cs 文件中添加 Swagger 服务和中间件。对于 .NET 6 及以上版本，代码如下：

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

然后在中间件管道中启用 Swagger UI：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
c.RoutePrefix = "api/docs"; // 可选：自定义访问路径
});

此时启动项目，访问 /swagger 或你设置的路径（如 /api/docs），即可看到自动生成的 API 页面。

Calliper 文档对比神器

文档内容对比神器

查看详情

添加注释支持

默认生成的文档不包含 XML 注释。要显示方法说明、参数描述等，需开启 XML 文档生成功能：

在项目文件（.csproj）中添加以下配置：

zuojiankuohaophpcnPropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<IncludeSymbolsInDocumentationFile>true</IncludeSymbolsInDocumentationFile>
</PropertyGroup>

然后在 AddSwaggerGen 中指定 XML 文件路径：

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

接着在代码中使用三斜线注释（///）为 API 添加说明：

/// <summary>
/// 获取所有用户信息
/// </summary>
/// <response code="200">成功返回用户列表</response>
[HttpGet]
public IActionResult GetUsers()
{
// ...
}

自定义 Swagger 配置（可选）

你可以进一步优化文档展示效果，例如：

修改 API 版本信息：

options.SwaggerDoc("v1", new OpenApiInfo
{
Title = "用户管理 API",
Version = "v1",
Description = "提供用户增删改查服务"
});

添加 JWT 认证支持：

options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Description = "请输入 JWT Token",
Name = "Authorization",
Type = SecuritySchemeType.Http,
Scheme = "bearer"
});
options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] {}
}
});

基本上就这些。集成完成后，Swagger 会实时反映你的 API 结构变化，无需手动维护文档，调试时还能直接在页面上测试接口，非常方便。

以上就是.NET Web API如何使用Swagger生成API文档的详细内容，更多请关注php中文网其它相关文章！