第三部分：Web应用开发
9. Swagger文档——API接口可视化
实例介绍
之前做电商后台API时，接口文档全靠手写：用Markdown写接口路径、参数、返回格式，每次接口改了都要同步改文档，经常忘，前端同事天天追着问“接口参数改了吗？返回字段加了吗？”；测试接口要打开Postman，手动填URL、参数、Header，慢得要死。后来集成了Swagger，接口文档自动生成，和代码同步更新，前端直接在Swagger页面调试vb.net教程C#教程python教程SQL教程access 2010教程接口，输入参数点“Try it out”就能看到返回结果，沟通成本降了80%，测试效率提升了好几倍。这节就带你从零配置Swagger，从基础文档到高级功能（JWT认证、版本控制、自定义UI），彻底告别“接口文档混乱”的痛苦。
需求分析
Swagger要解决“接口文档自动生成、在线调试、实时同步、认证支持、版本管理”的问题，具体需求如下：
1.基础文档生成：自动扫描API控制器，生成接口列表、参数、返回格式；
2.注释显示：显示接口、参数、DTO的XML注释，提升文档可读性；
3.JWT认证集成：支持在Swagger页面输入JWT令牌，调试需要认证的接口；
4.API版本控制：显示多个版本的API文档，比如v1、v2；
5.自定义UI：修改Swagger的标题、Logo、排序，隐藏内部接口；
6.文档导出：支持导出OpenAPI JSON、HTML、PDF格式；
7.环境控制：只在开发环境显示Swagger，生产环境隐藏；
8.权限保护：生产环境若需暴露Swagger，加密码保护；
9.接口分组：按模块（如用户管理、订单管理）分组显示接口；
10.错误示例：显示接口的错误返回格式，比如400、403、500的响应示例。
代码实现
前置条件：.NET 6+、ASP.NET Core Web API；需安装以下NuGet包：
Swashbuckle.AspNetCore：Swagger核心包（包含SwaggerGen、SwaggerUI）
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI界面
Swashbuckle.AspNetCore.Annotations：自定义Swagger注释（可选）
场景1：基础Swagger配置（自动生成文档）
从零开始配置Swagger，生成基础的API文档，支持在线调试。
步骤1：安装NuGet包
bash
dotnet add package Swashbuckle.AspNetCore
步骤2：配置Swagger服务（Program.cs）
csharp

	using Microsoft.OpenApi.Models;
	using System.Reflection;
	
	var builder = WebApplication.CreateBuilder(args);
	
	// 添加控制器服务
	builder.Services.AddControllers();
	
	// 1. 添加Swagger生成服务
	builder.Services.AddSwaggerGen(options =>
	{
	// 定义Swagger文档的版本和信息
	options.SwaggerDoc("v1", new OpenApiInfo
	{
	Title = "电商后台API",
	Version = "v1",
	Description = "电商后台用户、订单、商品管理API",
	Contact = new OpenApiContact
	{
	Name = "技术部",
	Email = "tech@example.com",
	Url = new Uri("https://example.com/tech")
	},
	License = new OpenApiLicense
	{
	Name = "MIT License",
	Url = new Uri("https://opensource.org/licenses/MIT")
	}
	});
	
	// 2. 读取XML注释（需在项目属性中启用XML文档文件）
	var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
	var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
	// includeControllerXmlComments: true 表示包含控制器的注释
	options.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
	});
	
	var app = builder.Build();
	
	// 3. 只在开发环境启用Swagger
	if (app.Environment.IsDevelopment())
	{
	// 启用Swagger JSON端点
	app.UseSwagger();
	// 启用Swagger UI界面
	app.UseSwaggerUI(options =>
	{
	// 指定Swagger JSON的路径
	options.SwaggerEndpoint("/swagger/v1/swagger.json", "电商后台API v1");
	// 设置Swagger UI的根路径（访问https://localhost:5001直接显示Swagger）
	options.RoutePrefix = string.Empty;
	// 展开所有接口分组
	options.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);
	// 显示请求时长
	options.DisplayRequestDuration();
	});
	}
	
	app.UseHttpsRedirection();
	app.UseAuthorization();
	app.MapControllers();
	
	app.Run();

步骤3：启用XML注释（项目属性设置）
1.右键项目 → 选择“属性”；
2.切换到“生成”选项卡；
3.勾选“XML文档文件”，默认路径为bin$(Configuration)$(TargetFramework)$(AssemblyName).xml；
4.取消勾选“警告”中的“XML文档文件的缺失的XML注释”（避免因未加注释报错）。
场景2：JWT认证集成（调试需要认证的接口）
配置Swagger支持JWT认证，在页面输入Token后直接调试需要认证的接口。
步骤1：配置Swagger JWT支持（Program.cs的AddSwaggerGen中添加）
csharp

	builder.Services.AddSwaggerGen(options =>
	{
	// ...之前的SwaggerDoc、XML注释配置
	
	// 3. 配置JWT认证支持
	options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
	{
	Name = "Authorization",
	Type = SecuritySchemeType.Http,
	Scheme = "Bearer",
	BearerFormat = "JWT",
	In = ParameterLocation.Header,
	Description = "请输入JWT令牌，格式：Bearer {token}，例如：Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
	});
	
	// 4. 指定哪些接口需要认证（全局配置，所有接口都需要）
	options.AddSecurityRequirement(new OpenApiSecurityRequirement
	{
	{
	new OpenApiSecurityScheme
	{
	Reference = new OpenApiReference
	{
	Type = ReferenceType.SecurityScheme,
	Id = "Bearer"
	}
	},
	Array.Empty<string>()
	}
	});
	});

步骤2：在Swagger页面调试认证接口
1.启动项目，访问https://localhost:5001；
2.点击右上角的“Authorize”按钮；
3.输入Bearer {你的JWT令牌}，点击“Authorize”；
4.现在可以调试需要[Authorize]的接口了，Swagger会自动在Header中带上Token。
场景3：API版本控制（多版本文档）
实现API版本控制，Swagger显示多个版本的文档，比如v1和v2。
步骤1：安装版本控制包
bash

	dotnet add package Microsoft.AspNetCore.Mvc.Versioning
	dotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

步骤2：配置版本控制服务（Program.cs）
csharp

	// 添加API版本控制
	builder.Services.AddApiVersioning(options =>
	{
	options.DefaultApiVersion = new ApiVersion(1, 0); // 默认版本v1.0
	options.AssumeDefaultVersionWhenUnspecified = true; // 未指定版本时使用默认版本
	options.ReportApiVersions = true; // 在响应Header中返回支持的版本
	});
	
	// 添加API版本探索服务（用于Swagger）
	builder.Services.AddVersionedApiExplorer(options =>
	{
	options.GroupNameFormat = "'v'VVV"; // 版本格式：v1、v2
	options.SubstituteApiVersionInUrl = true; // 在URL中替换版本号
	});

步骤3：配置多版本Swagger文档（Program.cs）
csharp

	// 注入API版本提供器
	var apiVersionDescriptionProvider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
	
	builder.Services.AddSwaggerGen(options =>
	{
	// 为每个API版本生成Swagger文档
	foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
	{
	options.SwaggerDoc(description.GroupName, new OpenApiInfo
	{
	Title = $"电商后台API {description.ApiVersion}",
	Version = description.ApiVersion.ToString(),
	Description = description.IsDeprecated ? "该版本已废弃，请使用最新版本" : "电商后台管理API"
	});
	}
	
	// ...之前的XML注释、JWT配置
	});

步骤4：配置Swagger UI显示多版本（Program.cs的UseSwaggerUI中添加）
csharp

	app.UseSwaggerUI(options =>
	{
	// 为每个版本添加Swagger端点
	foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
	{
	options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", 
	$"电商后台API {description.GroupName}");
	}
	
	// ...之前的RoutePrefix、DocExpansion配置
	});

步骤5：给控制器添加版本特性
csharp

	// v1版本控制器
	[ApiVersion("1.0")]
	[Route("api/v{version:apiVersion}/[controller]")]
	[ApiController]
	public class UsersController : ControllerBase
	{
	// ...接口方法
	}
	
	// v2版本控制器
	[ApiVersion("2.0")]
	[ApiVersion("2.1")] // 支持多个版本
	[Route("api/v{version:apiVersion}/[controller]")]
	[ApiController]
	public class UsersV2Controller : ControllerBase
	{
	// ...接口方法
	}

场景4：自定义Swagger UI（修改标题、Logo、隐藏接口）
自定义Swagger的UI样式，比如修改标题、添加Logo，隐藏内部接口。
步骤1：修改Swagger UI配置（Program.cs的UseSwaggerUI中添加）
csharp

	app.UseSwaggerUI(options =>
	{
	// ...之前的SwaggerEndpoint配置
	
	// 1. 修改Swagger页面标题
	options.DocumentTitle = "电商后台API文档";
	
	// 2. 添加自定义Logo（需将Logo图片放在wwwroot目录下）
	options.InjectStylesheet("/swagger-custom.css"); // 注入自定义CSS
	options.HeadContent = @"
	<img src='/logo.png' alt='Logo' style='width:100px; margin-bottom:10px;' />
	<h3>电商后台API文档</h3>
	";
	
	// 3. 隐藏指定接口（比如测试接口）
	options.DefaultModelsExpandDepth(-1); // 隐藏Schema模型
	options.DisplayOperationId(); // 显示接口的OperationId
	
	// 4. 自定义排序：按方法名排序（GET/POST/PUT/DELETE）
	options.OrderActionsBy((apiDesc) => $"{apiDesc.HttpMethod} {apiDesc.RelativePath}");
	});

步骤2：添加自定义CSS（wwwroot/swagger-custom.css）
css

	/* 修改Swagger UI的背景色 */
	.swagger-ui .topbar {
	background-color: #2c3e50;
	}
	
	/* 修改标题颜色 */
	.swagger-ui .info h1 {
	color: #2c3e50;
	}

步骤3：隐藏单个接口（用SwaggerIgnore特性）
csharp

	using Swashbuckle.AspNetCore.Annotations;
	
	// 隐藏这个接口，不显示在Swagger文档中
	[SwaggerIgnore]
	[HttpGet("test")]
	public IActionResult Test()
	{
	return Ok("测试接口");
	}

场景5：导出Swagger文档（JSON/HTML/PDF）
导出Swagger文档为JSON、HTML或PDF格式，方便分享给前端或测试。
步骤1：导出OpenAPI JSON
直接访问https://localhost:5001/swagger/v1/swagger.json，浏览器会下载JSON文件。
步骤2：导出HTML/PDF（用第三方工具）
在线工具：Swagger UI Export 或 Redocly；
本地工具：安装Swashbuckle.AspNetCore.SwaggerUI的导出插件，或用wkhtmltopdf将Swagger页面转为PDF。
逐行讲解
场景1：基础Swagger配置核心代码
1.AddSwaggerGen：
oSwaggerDoc：定义文档的版本、标题、描述、联系信息等，Swagger UI会显示这些信息；
oIncludeXmlComments：读取项目的XML注释文件，将接口、参数、DTO的注释显示在Swagger文档中；
2.UseSwagger：启用Swagger JSON端点，提供API的元数据；
3.UseSwaggerUI：
oSwaggerEndpoint：指定Swagger JSON的路径和显示名称；
oRoutePrefix = string.Empty：设置Swagger UI的根路径，访问网站根目录直接显示Swagger；
oDocExpansion.List：展开所有接口分组，默认是折叠的；
场景2：JWT认证集成核心代码
1.AddSecurityDefinition：定义JWT认证的方式，指定Token放在Header中，格式为Bearer {token}；
2.AddSecurityRequirement：全局配置所有接口需要JWT认证，若某些接口不需要认证，可在接口上添加[AllowAnonymous]特性；
场景3：API版本控制核心代码
1.AddApiVersioning：配置API版本的默认版本、未指定版本时的处理方式；
2.AddVersionedApiExplorer：配置版本的显示格式，用于Swagger生成多版本文档；
3.循环生成SwaggerDoc：为每个API版本生成对应的Swagger文档，废弃的版本会显示提示；
场景4：自定义Swagger UI核心代码
1.InjectStylesheet：注入自定义CSS，修改Swagger UI的样式；
2.HeadContent：在Swagger页面顶部添加自定义HTML，比如Logo、标题；
3.SwaggerIgnore：隐藏单个接口，不显示在Swagger文档中，适合测试接口或内部接口；
基础知识拓展

1. Swagger与OpenAPI的关系
   OpenAPI：是一种规范（以前叫Swagger规范），定义了API的描述格式，包括接口、参数、返回格式等；
   Swagger：是实现OpenAPI规范的工具集，包括Swagger Editor（编写OpenAPI文档）、Swagger UI（可视化文档）、Swagger Codegen（生成客户端代码）；
2. Swagger注释规范
   给接口、参数、DTO添加XML注释，Swagger会自动显示这些注释：
   csharp

	/// <summary>
	/// 获取用户列表
	/// </summary>
	/// <param name="page">页码，默认1</param>
	/// <param name="size">每页数量，默认10</param>
	/// <returns>用户列表分页结果</returns>
	[HttpGet]
	public async Task<ActionResult<PagedResult<UserDto>>> GetUsers(
	[FromQuery] int page = 1,
	[FromQuery] int size = 10)
	{
	// ...实现代码
	}
	
	/// <summary>
	/// 用户DTO
	/// </summary>
	public record UserDto( 
	/// <summary>用户ID</summary>
	int Id,
	/// <summary>用户名</summary>
	string UserName,
	/// <summary>邮箱</summary>
	string Email);

3. Swagger最佳实践
   1.只在开发环境启用：生产环境禁止暴露Swagger，避免泄露API信息；
   2.添加详细注释：给每个接口、参数、DTO添加注释，文档更易读；
   3.版本控制：API迭代时用版本控制，避免影响旧版本用户；
   4.认证集成：配置JWT/OAuth2认证，方便调试需要认证的接口；
   5.隐藏内部接口：用[SwaggerIgnore]隐藏测试接口或内部接口；
   6.导出文档：定期导出HTML/PDF文档，分享给前端或测试团队；

4. Swagger vs Postman
   | 特性 | Swagger | Postman |
   | ---- | ---- | ---- |
   | 文档生成 | 自动生成，与代码同步 | 手动编写或导入Swagger文档 |
   | 在线调试 | 直接在页面调试，无需额外工具 | 需要安装客户端，支持更复杂的调试 |
   | 团队协作 | 文档实时同步，无需共享文件 | 支持团队协作，需要同步集合 |
   | 代码生成 | 支持生成客户端代码 | 支持生成客户端代码 |
   | 环境配置 | 简单，适合开发环境 | 支持多环境配置，适合生产环境 |

5. 常见问题排查
   注释不显示：检查是否启用了XML注释，XML文件路径是否正确，注释格式是否符合XML规范；
   JWT认证不生效：检查AddSecurityDefinition和AddSecurityRequirement的配置是否正确，Token格式是否为Bearer {token}；
   多版本文档不显示：检查API版本控制的配置是否正确，控制器是否添加了[ApiVersion]特性；
   Swagger页面打不开：检查是否在开发环境启用，Swagger JSON端点是否能正常访问（/swagger/v1/swagger.json）；
   总结
   Swagger的价值在于自动生成文档、在线调试、实时同步、减少沟通成本，让API开发从“手写文档+Postman调试”变成“代码即文档+在线调试”，大幅提升开发效率。关键要点：
   1.基础配置：快速集成Swagger，生成基础的API文档；
   2.注释增强：添加XML注释，让文档更详细；
   3.认证集成：支持JWT/OAuth2，方便调试需要认证的接口；
   4.版本控制：实现多版本API，Swagger显示多个版本的文档；
   5.自定义UI：修改Swagger的样式，隐藏内部接口，提升用户体验；
   6.环境控制：只在开发环境启用Swagger，生产环境隐藏，保障安全；
   比如电商后台中，Swagger让前端同事直接在页面调试接口，不用再问后端“参数怎么填？返回格式是什么？”，后端修改接口后，文档自动更新，再也不用手动同步了。掌握Swagger，你开发的API会更专业、更易用、更高效！

本站原创，转载请注明出处：https://www.xin3721.com/ArticlecSharp/c49479.html