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

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 注释。

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

   

2. 在 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);
       }
       // --- 结束 ---
   });

6、运行项目