如何在.NET的Class library项目中配置Swagger

注意：Swagger本身依赖ASP.NET Core的Web宿主环境，无法在纯类库项目中独立启动运行，常规方案是将Swagger的配置逻辑、接口文档生成规则封装到类库中，供引用该类库的ASP.NET Core Web/API项目调用生效。

第一步：类库项目依赖安装 #

首先确认类库的目标框架与后续引用它的Web项目兼容（推荐.NET 6及以上版本），安装以下NuGet包：

• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.SwaggerGen
• 若需要封装SwaggerUI逻辑，额外安装Swashbuckle.AspNetCore.SwaggerUI

第二步：封装Swagger配置扩展方法 #

在类库中新增静态扩展类，将Swagger的服务注册、中间件注册逻辑全部封装为可复用的扩展方法，示例代码如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using System.Reflection;
using System.IO;

namespace YourClassLibNamespace
{
    public static class SwaggerConfigExtensions
    {
        // 注册Swagger服务的扩展方法
        public static IServiceCollection AddClassLibSwagger(this IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo 
                { 
                    Title = "类库API文档", 
                    Version = "v1" 
                });
                
                // 若要包含类库接口的XML注释，需先配置类库项目生成XML文档
                var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
                if (File.Exists(xmlFilePath))
                {
                    // 第二个参数传true可包含控制器注释、接口参数注释
                    c.IncludeXmlComments(xmlFilePath, true);
                }
            });
            return services;
        }

        // 启用Swagger中间件的扩展方法
        public static IApplicationBuilder UseClassLibSwagger(this IApplicationBuilder app)
        {
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "类库API V1");
            });
            return app;
        }
    }
}

如需生成XML注释，右键类库项目进入「属性-生成-输出」，勾选「XML文档文件」即可；.NET 6+项目也可直接在csproj文件中加入配置：<GenerateDocumentationFile>True</GenerateDocumentationFile>

第三步：在引用类库的Web/API项目中调用扩展 #

在需要启用该类库Swagger的上层Web项目的Program.cs中，直接调用类库封装好的扩展方法即可：

var builder = WebApplication.CreateBuilder(args);
// 调用类库封装的Swagger服务注册方法
builder.Services.AddClassLibSwagger();
// 其他服务注册逻辑...

var app = builder.Build();
// 调用类库封装的Swagger中间件启用方法
app.UseClassLibSwagger();
// 其他中间件配置逻辑...

app.Run();

特殊场景：类库包含Controller接口的适配 #

如果你的类库中直接定义了API Controller，需要让Swagger扫描到这些接口的话，还需要在上层Web项目的控制器注册逻辑中，添加类库的程序集作为应用部件：

using System.Reflection;

builder.Services.AddControllers()
    .AddApplicationPart(Assembly.Load("你的类库程序集名称"));

配置完成后，类库中的所有接口都会自动被Swagger识别并生成对应文档。

内容的提问来源于stack exchange，提问作者Govinda Rajbhar