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.
• 2.
• 3.

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();

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.
• 11.
• 12.
• 13.
• 14.
• 15.
• 16.
• 17.
• 18.
• 19.
• 20.
• 21.
• 22.
• 23.
• 24.
• 25.
• 26.
• 27.
• 28.
• 29.
• 30.
• 31.
• 32.
• 33.
• 34.
• 35.
• 36.
• 37.
• 38.
• 39.
• 40.
• 41.
• 42.
• 43.
• 44.
• 45.
• 46.
• 47.
• 48.
• 49.
• 50.
• 51.
• 52.
• 53.
• 54.
• 55.
• 56.
• 57.
• 58.
• 59.
• 60.
• 61.

在配置调整完成后，我们启动项目，打开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;  
    }  
}

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.
• 11.
• 12.
• 13.
• 14.
• 15.
• 16.
• 17.
• 18.
• 19.
• 20.
• 21.
• 22.
• 23.
• 24.
• 25.
• 26.
• 27.
• 28.
• 29.
• 30.
• 31.
• 32.
• 33.
• 34.
• 35.
• 36.
• 37.
• 38.
• 39.
• 40.
• 41.
• 42.
• 43.
• 44.
• 45.
• 46.
• 47.
• 48.
• 49.
• 50.
• 51.
• 52.
• 53.
• 54.
• 55.
• 56.
• 57.

然后，在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();

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.
• 11.
• 12.
• 13.
• 14.
• 15.
• 16.
• 17.
• 18.
• 19.
• 20.
• 21.
• 22.

原创作者: lsbc 转载于: https://blog.51cto.com/lsbc/11731139