ASP.NET Core Swagger接口文档（手把手教你集成Swagger生成API文档）

什么是 Swagger？

Swagger 是一套用于设计、构建、文档化和使用 RESTful Web 服务的开源工具集。其中最常用的是 Swagger UI，它能将 API 以可视化、可交互的方式展示出来，开发者可以直接在浏览器中测试接口。

在 .NET 生态中，我们通常使用 Swashbuckle.AspNetCore 这个 NuGet 包来集成 Swagger 到 ASP.NET Core 项目中。

第一步：创建 ASP.NET Core Web API 项目

如果你还没有项目，可以使用 .NET CLI 创建一个：

dotnet new webapi -n MyApiProjectcd MyApiProject

第二步：安装 Swashbuckle.AspNetCore 包

在项目根目录下执行以下命令安装 Swagger 支持包：

dotnet add package Swashbuckle.AspNetCore

第三步：配置 Swagger 服务

打开 Program.cs 文件（.NET 6+ 使用顶层语句），添加 Swagger 相关服务和中间件。

using Microsoft.OpenApi.Models;var builder = WebApplication.CreateBuilder(args);// 添加服务到容器builder.Services.AddControllers();// 注册 Swagger 生成器builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "My API",        Version = "v1",        Description = "一个使用 ASP.NET Core 和 Swagger 构建的示例 API"    });});var app = builder.Build();// 配置 HTTP 请求管道if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");        c.RoutePrefix = string.Empty; // 设置 Swagger UI 为网站根路径    });}app.UseHttpsRedirection();app.UseAuthorization();app.MapControllers();app.Run();

第四步：运行项目并查看 Swagger UI

在终端中运行：

dotnet run

默认启动后访问 https://localhost:5001（或 http://localhost:5000），你将看到如下图所示的 Swagger UI 页面。这就是你的 Swagger接口文档！

第五步：为 API 添加注释（可选但推荐）

为了让 C# Web API文档 更加详细，你可以为控制器和方法添加 XML 注释。

首先，在项目文件 .csproj 中启用 XML 文档生成：

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

然后在 Program.cs 中配置 Swagger 读取 XML 文件：

// 在 AddSwaggerGen 中添加var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);c.IncludeXmlComments(xmlPath);

现在，当你在控制器方法上添加三斜杠注释时，Swagger UI 会自动显示这些说明：

/// <summary>/// 获取所有用户/// </summary>/// <returns>用户列表</returns>[HttpGet]public IEnumerable<User> Get(){    return new List<User> { new User { Id = 1, Name = "张三" } };}

总结

通过以上步骤，你已经成功在 ASP.NET Core 项目中集成了 Swagger UI教程 所涵盖的核心功能。现在你的团队可以轻松查阅和测试 API 接口，无需额外编写冗长的文档。Swagger 不仅提升了开发体验，也增强了 API 的可维护性和可发现性。

记住，良好的 API 文档是专业开发的重要一环。借助 ASP.NET Core Swagger，你可以用最少的代码获得最高效的文档支持。

赶快动手试试吧！如果你觉得这篇 Swagger接口文档 教程对你有帮助，欢迎分享给更多开发者朋友。