.net6使用最小api（6）— 集成swagger扩展类方便直接拿用

前言

1、使用最小api集成swagger实践，通过集成服务的注入方式，即可快速实现swagger界面展示

2、可通过配置的方式，动态添加注释xml文件

以往最小api配置实战文章：

.net6使用最小api（1）——依赖注入Autofac之构造函数注入

.net6使用最小api（2）——依赖注入Autofac之属性注入

.net6使用最小api（3）— 自定义模型验证1

.net6使用最小api（4）— 自定义模型验证2

项目实战

1、添加AddSwaggerGen扩展类

添加文件名为SwaggerGenServiceCollectionExtensions的类，扩展方法如下：

publicstatic IServiceCollection AddSwaggerGenSetup(this IServiceCollection services, Action swaggerOption)
{
    // 添加Swagger
    services.AddSwaggerGen(option =>
    {
        option.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "API Demo",
            Version = "v1",
            Description = "API文档描述",
            Contact = new OpenApiContact
            {
                Email = "79522860@qq.com",
                Name = "dylan",
                Url = new Uri("https://github.com/hailang2ll")
            },
            License = new OpenApiLicense
            {
                Name = "许可证名称",
                Url = new Uri("https://github.com/hailang2ll")
            }


        });
        // 获取xml文件名
        //var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        // 获取xml文件路径
        //var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        // 添加控制器层注释，true表示显示控制器注释
        #region 加载实体注释
        SwaggerOption swaggerConfig = new SwaggerOption();
        swaggerOption?.Invoke(swaggerConfig);
        if (swaggerConfig == null)
        {
            ConsoleHelper.WriteErrorLine($"SwaggerGen xml load fail;swaggerOption is null");
        }
        else
        {
            if (swaggerConfig.RootPath.IsNullOrEmpty() || swaggerConfig.XmlFiles.IsNullOrEmpty())
            {
                ConsoleHelper.WriteErrorLine($"SwaggerGen xml load fail;swaggerOption.RootPath or XmlFiles is null");
            }
            else
            {
                var basePath = swaggerConfig.RootPath; //AppContext.BaseDirectory;
                foreach (var item in swaggerConfig.XmlFiles)
                {
                    var xmlPath = Path.Combine(basePath, item);
                    if (File.Exists(xmlPath))
                    {
                        option.IncludeXmlComments(xmlPath, true);
                        ConsoleHelper.WriteSuccessLine($"SwaggerGen.contracts load success:path={xmlPath}");
                    }
                    else
                    {
                        ConsoleHelper.WriteErrorLine($"SwaggerGen xml load fail;path={xmlPath}");
                    }
                }
            }


        }
        #endregion
    });
    return services;
}

2、添加UseSwaggerUI扩展类

添加类文件名为SwaggerUIBuilderExtensions的扩展，如下代码：

/// 

/// 
/// 
/// 
/// 
/// 
public static IApplicationBuilder UseSwaggerUI(this IApplicationBuilder app, bool isDebug)
{
    if (isDebug)
    {
        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", AppDomain.CurrentDomain.FriendlyName);
            // 路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,注意localhost:8001/swagger是访问不到的，去launchSettings.json把launchUrl去掉，如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "doc";
            //c.RoutePrefix = "";
           
        });
    }
    return app;
}

3、最小api调用方法：

可动态指定添加多个注释文件

builder.Services.AddSwaggerGenSetup(option =>
{
    option.RootPath = AppContext.BaseDirectory;
    option.XmlFiles = new List {
        AppDomain.CurrentDomain.FriendlyName+".xml",
        "DMS.IServices.xml"  //可追加其它注释xml文件
    };
});

app.UseSwaggerUI(true);

4、效果如下

5、总结

虽然在最小api中集成swagger很简单，但也有很多朋友会将swagger相关的代码写在Program中，个人感觉扩展不是很强，而且很臃肿，此文章主要通过扩展类的形式注册到service中运行，方便代码的维护与扩展。