c# .Net Core 项目配置SWagger UI 带Token访问

简介

Swagger是一款强大的API管理工具，它主要用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger通过一套标准的规范定义接口及其相关信息，从而能够自动生成各种格式的接口文档（如HTML、PDF、Markdown等），并支持生成多种语言和客户端、服务端的代码，以及提供在线接口调试页面，极大地方便了开发人员进行接口的开发和测试。

在ASP.NET Core的Web API项目中，通常会默认注入Swagger服务，但是默认的Swagger并没有开启挈带Token配置功能。如需开启，需要在Swagger的配置中添加一些特定的设置。

默认配置

在新建的WebApi项目的Program文件中，默认会有下面这三个配置，这三行代码行是配置和使用Swagger的关键步骤。下面我们先来了解这三行代码的具体作用。

builder.Services.AddSwaggerGen();
app.UseSwagger();
app.UseSwaggerUI();

1. **builder.Services.AddSwaggerGen();**这行代码是在项目的服务配置阶段调用的，它的作用是向ASP.NET Core的依赖注入（DI）容器中添加Swagger生成器的服务。Swagger生成器负责扫描你的控制器和动作，并基于这些信息生成Swagger文档（通常是一个JSON文件），这个文档描述了你的API的结构，包括可用的端点、请求方法、请求和响应格式等。你还可以在这个调用中配置Swagger生成器的各种选项，比如文档标题、版本、要包括或排除的API控制器、安全定义等，如之前示例中所示。
2. **app.UseSwagger();**这行代码是在应用程序的请求处理管道中配置Swagger中间件的。它告诉ASP.NET Core，当请求匹配到Swagger文档的路径（默认情况下是/swagger/{documentName}/swagger.json）时，应该使用Swagger中间件来处理这些请求。Swagger中间件的作用就是提供Swagger文档的JSON表示，这个文档可以被Swagger UI或其他工具用来渲染API文档。注意，这个中间件本身并不提供UI界面，它只是提供了一个JSON格式的API描述文档。
3. **app.UseSwaggerUI();**这行代码也是在应用程序的请求处理管道中配置的，但它添加的是Swagger UI的中间件。Swagger UI是一个Web UI，它允许你浏览和测试你的RESTful API。当你访问Swagger UI的路径（默认情况下是/swagger或/swagger/index.html）时，这个中间件会处理请求，并提供一个用户友好的界面来显示你的API文档，并允许你发送请求到你的API端点。你可以在这个调用中配置Swagger UI的各种选项，比如文档标题、Swagger JSON文件的路径、OAuth2客户端配置等。

Swagger配置添加设置

为了在测试API时能够发送带有认证信息的请求，我们需要在Swagger的配置中添加一些特定的设置。这些设置包括如何向Swagger UI展示认证方式（如Bearer Token），并允许用户在UI中输入Token值。

var builder = WebApplication.CreateBuilder(args);  
  
// 添加服务  
builder.Services.AddControllers();  
  
// 添加Swagger生成器  
builder.Services.AddEndpointsApiExplorer();  
builder.Services.AddSwaggerGen(c =>  
{  
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });  
  
    // 添加Bearer认证  
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme  
    {  
        Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",  
        Name = "Authorization",  
        In = ParameterLocation.Header,  
        Type = SecuritySchemeType.ApiKey,  
        Scheme = "Bearer"  
    });  
  
    // 为API添加Bearer认证需求  
    c.AddSecurityRequirement(new OpenApiSecurityRequirement()  
    {  
        {  
            new OpenApiSecurityScheme  
            {  
                Reference = new OpenApiReference  
                {  
                    Type = ReferenceType.SecurityScheme,  
                    Id = "Bearer"  
                },  
                Scheme = "oauth2",  
                Name = "Bearer",  
                In = ParameterLocation.Header,  
            },  
            new List<string>()  
        }  
    });  
});  
  
var app = builder.Build();  
  
// 配置Swagger中间件  
if (app.Environment.IsDevelopment())  
{  
    app.UseSwagger();  
    app.UseSwaggerUI(c =>  
    {  
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");  
        // 可以在这里配置Swagger UI的其他选项，比如OAuth2客户端配置  
    });  
}  
  
app.UseHttpsRedirection();  
  
app.UseAuthorization();  
  
app.MapControllers();  
  
app.Run();

在配置调整完成后，我们启动项目，打开swagger UI ，可以在右上角看到一个Authorize的按钮。

点击按钮，会出现一个弹窗，我们只需要在value中输入我们的token。

届时再发送请求，我们的请求头中就会携带设置的token了。

(优化)使用扩展方法配置

像上面这样配置swagger会导致program很冗余，我们可以将Swagger的配置放入一个单独的扩展类使

Program.cs

文件更加整洁和易于管理。

首先，创建一个新的静态类，比如命名为

SwaggerExtensions

，并在其中定义一个扩展方法来配置Swagger。

using Microsoft.AspNetCore.Builder;  
using Microsoft.Extensions.DependencyInjection;  
using Microsoft.OpenApi.Models;  
  
public static class SwaggerExtensions  
{  
    public static IServiceCollection AddCustomSwagger(this IServiceCollection services)  
    {  
        services.AddSwaggerGen(c =>  
        {  
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });  
  
            // 添加Bearer认证  
            c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme  
            {  
                Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",  
                Name = "Authorization",  
                In = ParameterLocation.Header,  
                Type = SecuritySchemeType.ApiKey,  
                Scheme = "Bearer"  
            });  
  
            // 为API添加Bearer认证需求  
            c.AddSecurityRequirement(new OpenApiSecurityRequirement()  
            {  
                {  
                    new OpenApiSecurityScheme  
                    {  
                        Reference = new OpenApiReference  
                        {  
                            Type = ReferenceType.SecurityScheme,  
                            Id = "Bearer"  
                        },  
                    },  
                    new List<string>()  
                }  
            });  
        });  
  
        return services;  
    }  
  
    public static IApplicationBuilder UseCustomSwagger(this IApplicationBuilder app)  
    {  
        if (app.Environment.IsDevelopment())  
        {  
            app.UseSwagger();  
            app.UseSwaggerUI(c =>  
            {  
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");  
                // 可以在这里配置Swagger UI的其他选项  
            });  
        }  
  
        return app;  
    }  
}

然后，在

Program.cs

中，使用这些扩展方法来配置Swagger：

var builder = WebApplication.CreateBuilder(args);  
  
builder.Services.AddControllers();  
builder.Services.AddEndpointsApiExplorer();  
builder.Services.AddCustomSwagger(); // 使用扩展方法添加Swagger服务  
  
// 其他服务配置...  
  
  
var app = builder.Build();  
  
app.UseCustomSwagger(); // 使用扩展方法配置Swagger中间件  
  
// 其他中间件配置...  
  
app.UseHttpsRedirection();  
app.UseAuthentication();  
app.UseAuthorization();  
  
app.MapControllers();  
  
app.Run();