12Swagger文档支持 - ASP.NET Core WebAPI

---

前言

直接创建Swagger文档的WebAPI：

在创建ASP.NET Core Web API项目时，可以直接勾选“启用OpenAPI支持”，就会自动创建Swagger文档的WebAPI。

下文介绍如何手动配置Swagger文档支持。

---

手动配置Swagger支持

一、添加Swagger相关类

在Nuget中添加Microsoft.AspNetCore.OpenApi和Swashbuckle.AspNetCore类库。

二、配置Swagger相关信息

在program.cs文件中添加相关信息。

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

在launchSettings.json文件中修改默认启动地址为swagger。

点击启动项目，即会打开swagger文档的接口页面。

三、接口如何支持授权信息（token）

在swagger文档的接口里，没有输入JWT的入口。同样需要配置一下信息。

1. 实现类

需要继续接口IOperationFilter，实现Apply方法，定义安全方案（安全方案的Id后面也会使用）。

public class AuthorizationHeaderOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Security == null)
            operation.Security = new List<OpenApiSecurityRequirement>();

        var scheme = new OpenApiSecurityScheme()
        {
            Reference = new OpenApiReference() { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
        };

        //OpenApiSecurityRequirement a = new OpenApiSecurityRequirement();
        //a.Add(scheme, new List<string>());
        //operation.Security.Add(a);
        //注释代码和以下代码是同样的
        operation.Security.Add(new OpenApiSecurityRequirement()
        {
            [scheme] = new List<string>()
        });
        

    }
}

2. 定义安全方案

在program.cs文件中定义安全方案的具体形式。

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<AuthorizationHeaderOperationFilter>();

    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
    {
        Scheme = "Bearer",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        In = ParameterLocation.Header
    });
});

3. 使用形式

配置好信息后，不影响正常接口使用，只会在swagger接口页面中生成输入token的入口，以及每个接口都一个锁的图标。

在此页面输入token参数，即可正常访问接口。