.NET Core6.0中的Swagger的配置和使用

1、配置swagger

/// <summary>
/// 配置swagger
/// </summary>
/// <param name="services"></param>
/// <exception cref="ArgumentNullException"></exception>
public static void AddSwaggerConfig(this IServiceCollection services)
{
    if (services == null) throw new ArgumentNullException(nameof(services));

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "FyyAdmin.NET Api - .NET6",
            Version = "v1",
            Description = "",
        });
        try
        {
            //添加文档注释
            c.IncludeXmlComments("FyyAdmin.xml", true);
        }
        catch (Exception ex)
        {
            Console.WriteLine("swagger 文档加载失败" + ex.Message);
        }

        //参考文章：http://www.zyiz.net/tech/detail-134965.html
        //需要安装包Swashbuckle.AspNetCore.Filters
        //开启权限小锁 需要在对应的Action上添加[Authorize]才能看到
        c.OperationFilter<AddResponseHeadersFilter>();
        c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();

        //在header 中添加token，传递到后台
        c.OperationFilter<SecurityRequirementsOperationFilter>();

        //需要安装包Microsoft.AspNetCore.Authentication.JwtBearer和Microsoft.OpenApi
        c.AddSecurityDefinition(JwtBearerDefaults.AuthenticationScheme,
            new OpenApiSecurityScheme
            {
                In = ParameterLocation.Header,
                Description = "请输入Login接口返回的Token，前置Bearer。示例：Bearer {Token}",
                Name = "Authorization",//jwt默认的参数名称,
                Type = SecuritySchemeType.ApiKey, //指定ApiKey
                BearerFormat = "JWT",//标识承载令牌的格式 该信息主要是出于文档目的
                Scheme = JwtBearerDefaults.AuthenticationScheme//授权中要使用的HTTP授权方案的名称
            });
        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
                },
                new List<string>()
            }
        });
    });
}

2、在Program.cs添加Swagger，并添加配置

Swashbuckle.AspNetCore.SwaggerGen

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSwaggerGen();

builder.Services.AddSwaggerConfig();

3、定制化使用方法

/// <summary>
/// 使用swagger
/// </summary>
/// <param name="app"></param>
public static void UseSwagger(this IApplicationBuilder app)
{
    app.UseSwagger(c =>
    {
        c.RouteTemplate = "swagger/{documentName}/swagger.json";
        c.PreSerializeFilters.Add((swaggerDoc, httpReq) =>
        {
            var url = $"{httpReq.Scheme}://{httpReq.Host.Value}";
            var referer = httpReq.Headers["Referer"].ToString();
            if (referer.Contains(GlobalConstant.DevApiProxy))
                url = referer.Substring(0,
                    referer.IndexOf(GlobalConstant.DevApiProxy, StringComparison.InvariantCulture) + GlobalConstant.DevApiProxy.Length - 1);
            swaggerDoc.Servers =
                new List<OpenApiServer>
                {
                    new OpenApiServer
                    {
                        Url = url
                    }
                };
        });
    });

    app.UseSwaggerUI(c => c.SwaggerEndpoint("v1/swagger.json", "FyyAdmin v1"));
}

其中的GlobalConstant类如下：

/// <summary>
/// 全局静态常量
/// </summary>
public class GlobalConstant
{
    /// <summary>
    /// 管理员权限
    /// </summary>
    public static string AdminPerm = "*:*:*";

    /// <summary>
    /// 管理员角色
    /// </summary>
    public static string AdminRole = "admin";

    /// <summary>
    /// 开发版本API映射路径
    /// </summary>
    public static string DevApiProxy = "/dev-api/";

    /// <summary>
    /// 用户权限缓存key
    /// </summary>
    public static string UserPermKEY = "CACHE-USER-PERM";

    /// <summary>
    /// 欢迎语
    /// </summary>
    public static string[] WelcomeMessages = new string[] {
        "欢迎使用！"
    };
}

4、在Program.cs中使用

var app = builder.Build();

app.UseSwagger();

5、如果启动调试时，没有浏览器页面弹出，则需进行如下勾选：

调试-->选项-->常规

.NET Core6.0中的Swagger的配置和使用

猜你喜欢