Swagger是一个开源工具，用于设计、构建、文档化和使用RESTful Web服务。它可以为我们的WebApi提供一个交互式的文档界面，使我们能够更轻松地测试、调试和使用我们的API。
在本文中，我们将探讨如何在.NetCore 3.1 WebApi中配置Swagger以及一些常用的配置选项。
安装Swagger
首先，我们需要安装Swagger到我们的.NetCore WebApi项目中。打开Visual Studio的NuGet包管理控制台，并运行以下命令：
Install-Package Swashbuckle.AspNetCore
配置Swagger
安装完Swashbuckle.AspNetCore之后，我们需要在Startup.cs文件中的ConfigureServices方法中进行Swagger的配置。在这个方法中，我们需要添加以下代码：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
上述代码将添加Swagger生成器（SwaggerGen）到我们的服务容器中，并配置API文档的标题和版本。
然后，在Configure方法中，我们需要添加以下代码：
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
上述代码将Swagger中间件添加到HTTP请求管道中，并配置SwaggerUI的地址以及文档的标题。
启用Swagger验证
Swagger默认情况下是不启用身份验证的，任何用户都可以访问API文档。然而，我们可以通过添加身份验证配置来保护我们的API文档。例如，我们可以使用JWT身份验证来验证访问API文档的用户。
要启用Swagger验证，我们可以在ConfigureServices方法中添加以下代码：
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",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
Scheme = "Bearer"
});
// 启用Bearer身份验证
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] {}
}
});
});
上述代码会添加一个名为"Bearer"的身份验证定义，并启用Bearer身份验证。在API文档中，用户将需要提供有效的JWT令牌（通过Authorization header）才能访问受保护的API接口。
配置Swagger注释
Swagger的一个重要功能是它可以根据我们的代码注释自动生成API文档。因此，我们应该为每个控制器和操作添加有意义的注释。
在我们的控制器类和操作方法上添加注释，例如：
/// <summary>
/// 获取所有用户
/// </summary>
/// <returns>用户列表</returns>
/// <response code="200">操作成功</response>
[HttpGet]
public IActionResult GetAllUsers()
{
// 实现代码
}
上述代码将为GetAllUsers操作添加了注释，并定义了返回码200表示操作成功。当我们生成API文档时，Swagger会自动根据这些注释生成适当的文档信息。
配置Swagger美化样式
Swagger UI默认提供了一些简单的样式和主题。然而，我们可以通过添加Swagger UI的自定义CSS来美化我们的API文档界面。
我们可以在wwwroot文件夹下创建一个名为swagger-ui.css的CSS文件，并添加自己的样式。然后，在ConfigureServices方法中添加以下代码来加载自定义CSS：
services.AddSwaggerGen(c =>
{
// ...
// 加载自定义CSS
c.InjectStylesheet("/swagger-ui.css");
});
上述代码将加载位于项目的wwwroot文件夹下名为swagger-ui.css的CSS文件。
结论
本文中，我们学习了如何在.NetCore 3.1 WebApi中配置Swagger并进行一些常用的配置选项。我们还了解了如何启用Swagger验证并配置Swagger注释。最后，我们还学习了如何美化我们的API文档界面。
Swagger提供了一种简单而强大的方式来构建、文档化和使用我们的API。希望本文对你有所帮助，谢谢阅读！
本文来自极简博客，作者：心灵捕手，转载请注明原文链接：.NetCore3.1 WebApi中Swagger配置
