【20220426】.NET6 WebApi Swagger配置

.NET6 WebApi Swagger配置

环境准备

Visual Studio 2022 
NET6 平台

一、配置版本控制

1、准备版本枚举

/// <summary>
/// 版本枚举
/// </summary>
public enum ApiVersions
{
   V1,
   V2
}

2、控制器标记特性

/// <summary>
/// 信息资源
/// </summary>
[ApiExplorerSettings(IgnoreApi = false, GroupName = nameof(ApiVersions.V1))]
[ApiController]
[Route("/api/[controller]/[action]")]
public class ValuesController : ControllerBase
{
​
}

注意：ApiVersions.V1就是枚举中的版本号了

3、在项目控制台中配置

var builder = WebApplication.CreateBuilder(args);
....
builder.Services.AddSwaggerGen(option =>
{
    #region 分版本的Swagger配置
    {
        //要启用swagger版本控制要在api控制器或者方法上添加特性[ApiExplorerSettings(GroupName = "版本号")]  我这里是枚举
        typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
        {
            option.SwaggerDoc(version, new OpenApiInfo()
            {
                Title = $"{version}:Api文档",
                Version = version,
                Description = $"通用版本的CoreApi版本{version}"
            });
        });
    }
    #endregion
}

4、引用中间件

var app = builder.Build();
​
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    foreach (string version in typeof(ApiVersions).GetEnumNames())
    {
        c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"版本：{version}");
    }
});

 

二、配置展示注释

1、配置控制台

var builder = WebApplication.CreateBuilder(args);
....
builder.Services.AddSwaggerGen(option =>
{  
        // xml文档绝对路径 
        var file = Path.Combine(AppContext.BaseDirectory, "ZhaoXi.NET6Demo.Api.xml");  
        // true : 显示控制器层注释
        option.IncludeXmlComments(file, true); 
        // 对action的名称进行排序，如果有多个，就可以看见效果了。
        option.OrderActionsBy(o => o.RelativePath);  
}

2、Use中间件

var app = builder.Build();
 
app.UseSwagger();
app.UseSwaggerUI();

 

3、配置生成Xml文件

鼠标右键--->项目--->属性--->生成--->输出   勾选文档文件---生成包含Api文档的文件

三、配置支持Token验证

1、配置项目控制台

var builder = WebApplication.CreateBuilder(args);
....
builder.Services.AddSwaggerGen(option =>
{ 
    //添加安全定义
    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "请输入token,格式为 Bearer xxxxxxxx（注意中间必须有空格）",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    //添加安全要求
    option.AddSecurityRequirement(new OpenApiSecurityRequirement {
        {
            new OpenApiSecurityScheme
            {
                Reference =new OpenApiReference()
                {
                    Type = ReferenceType.SecurityScheme,
                    Id ="Bearer"
                }
            },
            new string[]{ }
        }
     });
}