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

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

月夜之吻

发布： 2025-11-09 13:10:03

原创

563人浏览过

答案：本文介绍在.NET Web API中集成Swagger的方法。首先安装Swashbuckle.AspNetCore包，然后在Program.cs中添加AddEndpointsApiExplorer和AddSwaggerGen服务，并配置UseSwagger与UseSwaggerUI中间件以启用文档界面；接着通过启用XML文档生成并指定路径实现详细注释展示，包括控制器摘要和响应码；最后可自定义标题、版本信息及JWT认证支持，提升API文档可读性与测试便利性，从而提高开发效率和协作体验。

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

在开发 .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();

说明：

Calliper 文档对比神器

文档内容对比神器

查看详情

AddEndpointsApiExplorer()：用于收集 API 元数据。
AddSwaggerGen()：生成 OpenAPI 文档。
UseSwagger()：启用 Swagger JSON 端点（如 /swagger/v1/swagger.json）。
UseSwaggerUI()：提供可视化界面，默认路径为 /swagger。

3. 添加控制器和 Action 的注释文档

为了让 Swagger 显示更详细的说明，建议为控制器和方法添加 XML 注释。这些注释会自动显示在 Swagger UI 中。

步骤如下：

在 .csproj 文件中启用 XML 文档生成：

<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup>

在 AddSwaggerGen 中指定 XML 文件路径：

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

为控制器或方法添加 XML 注释，例如：

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

这样，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 注释和路径配置，建议每个项目都标准化启用。

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