当前位置：首页 > news >正文

使用C#/.NET8 从零开始搭建微服务项目（三）—————— 配置Swagger文档

news 2026/5/12 21:21:04

1、在项目中加一个控制器，添加一个空的测试接口

2、程序包安装

需要在项目中安装 Swashbuckle.AspNetCore。在“程序包管理器控制台”中运行以下命令，或通过 NuGet 包管理器搜索安装。

Install-Package Swashbuckle.AspNetCore

3、配置服务与中间件

安装好包之后，需要在项目的入口文件（Program.cs 或 Startup.cs）中进行配置。
在 Program.cs 文件中，找到 builder.Services 和 app 部分，添加以下代码

using Microsoft.OpenApi;var builder = WebApplication.CreateBuilder(args);builder.Services.AddControllers();
// 添加 API 探索功能 (对于某些模板是必需的)
builder.Services.AddEndpointsApiExplorer();
// 1. 注册 Swagger 生成器服务
builder.Services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo{Title = "基本信息接口",Version = "v1",Description = "测试搭建微服务中的基本信息API模块"});
});var app = builder.Build();// 2. 启用中间件来生成 OpenAPI 规范的 JSON 文件
app.UseSwagger();
// 3. 启用中间件来提供 Swagger UI 界面
app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "基本信息接口");
});app.UseHttpsRedirection();
app.MapControllers();
app.Run();

4、修改启动项launchSettings.json

启动项目后，就可以看到一个swagger接口文档。但是我们可以看到控制器和接口的注释说明并没有显示出来

5、添加XML注释

默认情况下，Swagger UI 只能看到接口的路径和参数。为了让文档更详细（显示接口作用、参数含义等），我们需要启用代码中的 XML 注释。

启用 XML 文档生成：在 Visual Studio 中，右键点击项目 -> 属性 -> “生成”选项卡，勾选“输出”下的 “生成包含API文档的文件”。系统会生成一个 项目名.xml 的文件。

在 Swagger 中引入注释：在配置 AddSwaggerGen 时，添加读取 XML 文件的代码。

builder.Services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo{Title = "基本信息接口",Version = "v1",Description = "测试搭建微服务中的基本信息API模块"});// --- 新增：引入 XML 注释 ---var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);if (basePath != null){c.IncludeXmlComments(Path.Combine(basePath, "Test.InfoApi.xml"), true);}// --- 结束 ---
});