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