Swashbuckle.AspNetCore
OpenAPI (Swagger) 工具，用于基于 ASP.NET Core 构建的 API。
直接从您的应用程序代码生成精美的 API 文档，包括一个用于探索和测试操作的 UI。
除了其 Swagger 2.0 和 OpenAPI 3.0/3.1 生成器外，Swashbuckle.AspNetCore 还提供 一个嵌入版本的出色的 swagger-ui 项目，该项目由生成的 OpenAPI JSON 文档提供支持。 这意味着您可以为 API 补充始终与最新代码保持同步的实时文档。最重要的是，它 需要最少的编码和维护，让您能够专注于构建出色的 API。
但这还不是全部！
一旦您拥有一个可以用 OpenAPI 文档描述自身的 API，您就打开了基于 OpenAPI 的 工具宝库，其中包括一个可以针对广泛流行平台的客户端生成器。有关更多详细信息，请参阅 swagger-codegen
[!IMPORTANT]
Swashbuckle.AspNetCore 10.0 版本由于将我们对 Microsoft.OpenApi 的依赖升级到 2.x.x 版本以支持生成 OpenAPI 3.1 文档，因此引入了破坏性变更。详情请参阅 迁移到 Swashbuckle.AspNetCore v10。
兼容性
| Swashbuckle 版本 | ASP.NET Core | OpenAPI/Swagger 版本 | Microsoft.OpenApi | swagger-ui | Redoc |
|---|---|---|---|---|---|
%5B1%5D&prefix=v&suffix=-*&logo=github&label=CI){kind=icon} | >= 8.0.0 | 3.1, 3.0, 2.0 |  |  |  |
 | >= 8.0.0 | 3.1, 3.0, 2.0 |  |  |  |
 | 9.0.x, 8.0.x | 3.0, 2.0 |  |  |  |
 | 9.0.x, 8.0.x, 2.3.x | 3.0, 2.0 |  |  |  |
入门指南
首先，将 kitchen-sink NuGet 包安装到您的 ASP.NET Core 应用程序中：
dotnet add package Swashbuckle.AspNetCore
接下来，在应用程序的启动路径中注册 OpenAPI (Swagger) 生成器，并定义一个或多个 OpenAPI 文档。例如：
using Microsoft.OpenApi;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMvc();
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
var app = builder.Build();
app.UseSwagger();
app.Run();确保你的 API 端点及其参数在适当的位置使用 [Http*] 和 [From*] 特性进行装饰。
[HttpPost]
public void CreateProduct([FromBody] Product product)
{
// Implementation goes here
}
[HttpGet]
public IEnumerable<Product> SearchProducts([FromQuery] string keywords)
{
// Implementation goes here
return [];
}[!NOTE] 如果你省略了显式的参数绑定，生成器默认会将它们描述为 "query" 参数。
然后，使用以下方法之一暴露 OpenAPI JSON 文档端点：
- 如果你使用的是基于端点的路由，请添加端点：
// Your own endpoints go here, and then...
app.MapSwagger();- 添加 OpenAPI 中间件：
app.UseSwagger();此时，你可以启动应用程序，并在 /swagger/v1/swagger.json 查看生成的 OpenAPI 文档。
最后，你可以选择性地添加 swagger-ui 中间件以暴露交互式文档，并指定用于提供其内容的 OpenAPI 文档：
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("v1/swagger.json", "My API V1");
});现在你可以重启应用程序，并在 /swagger 查看自动生成的交互式文档。
System.Text.Json (STJ) vs Newtonsoft.Json (Json.NET)
在 Swashbuckle.AspNetCore 的 5.0.0 之前的版本中，Swashbuckle.AspNetCore 会基于
Newtonsoft.Json 序列化器 的行为生成 Schemas（API 暴露的数据类型的描述）。这在当时是合理的，因为那是随 ASP.NET Core
一起发布的序列化器。然而，自 ASP.NET Core 3.0 起，ASP.NET Core 开箱即用地引入了新的序列化器 System.Text.Json (STJ)。
如果你想使用 Newtonsoft.Json，你必须安装一个单独的包并显式选择加入。默认情况下，Swashbuckle.AspNetCore 会假设 你正在使用 System.Text.Json 序列化器，并基于其行为生成 schemas。如果你正在使用 Newtonsoft.Json，则需要安装一个 单独的 Swashbuckle.AspNetCore 包 Swashbuckle.AspNetCore.Newtonsoft 以显式选择加入。
以下是针对 ASP.NET Core MVC 执行此操作的示例：
dotnet add package Swashbuckle.AspNetCore.Newtonsoft
services.AddMvc();
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
services.AddSwaggerGenNewtonsoftSupport();Swashbuckle、ApiExplorer 和路由
Swashbuckle 严重依赖于 ApiExplorer，即随 ASP.NET Core 一起发布的 API 元数据层。如果你使用 AddMvc(...)
辅助方法来引导 MVC 堆栈，那么 API Explorer 将自动注册，Swashbuckle.AspNetCore 应该可以正常工作。
然而，如果你使用 AddMvcCore(...) 来构建更精简的 MVC 堆栈，则需要显式添加 API Explorer 服务：
services.AddMvcCore()
.AddApiExplorer();此外，如果你使用的是 约定路由（而非特性路由），那么任何使用约定路由的控制器以及这些控制器上的操作都不会在 API Explorer 中表示，这意味着 Swashbuckle 将无法找到这些控制器并 为它们生成 OpenAPI 操作。
例如：
app.UseMvc(routes =>
{
// SwaggerGen won't find controllers that are routed via this technique.
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});对于你希望在 OpenAPI 文档中表示的任何控制器，你必须使用特性路由：
[Route("example")]
public class ExampleController : Controller
{
[HttpGet("")]
public IActionResult DoStuff()
{
// Your implementation
return Empty;
}
}有关更多信息，请参阅 ASP.NET Core MVC 路由文档。
组件
Swashbuckle.AspNetCore 由多个组件组成，可根据需求组合使用或单独使用。
其核心包括一个 OpenAPI 生成器、用于将 OpenAPI（Swagger）文档作为 JSON 端点暴露的中间件，以及
swagger-ui 的打包版本。这三个包可以通过 Swashbuckle.AspNetCore
"元包" 进行安装，并将协同工作（参见 Getting Started），以提供从代码中自动生成的 API 文档。
此外，还有附加包（CLI 工具、使用 Redoc 的替代 UI 等），可根据需要安装和配置。
"核心" 包
| Package | NuGet | Description |
|---|---|---|
| Swashbuckle.AspNetCore.Swagger |  | 暴露 OpenAPI JSON 端点。它期望在 DI 容器中注册 ISwaggerProvider 的实现，并查询以获取 OpenApiDocument 实例，然后将其作为序列化的 JSON 暴露。 |
| Swashbuckle.AspNetCore.SwaggerGen |  | 注入 ISwaggerProvider 的实现，可供上述组件使用。此特定实现从您的应用程序端点（控制器、最小端点等）生成 OpenApiDocument 实例。 |
| Swashbuckle.AspNetCore.SwaggerUI |  | 暴露 swagger-ui 的嵌入式版本。您指定它可以从中获取 OpenAPI 文档的 API 端点，并使用它们为您的 API 提供交互式文档。 |
Additional Packages
| Package | NuGet | Description |
|---|---|---|
| Swashbuckle.AspNetCore.Annotations |  | 包含一组可应用于控制器/端点、操作和模型的自定义特性，以丰富生成的文档。 |
| Swashbuckle.AspNetCore.Cli |  | 提供一个命令行界面 (CLI)，用于直接从应用程序启动程序集检索 OpenAPI 文档，然后写入文件。 |
| Swashbuckle.AspNetCore.ReDoc |  | 公开 Redoc UI（swagger-ui 的替代方案）的嵌入式版本。 |
Community Packages
这些包由 .NET 开源社区提供。
| Package | NuGet | Description |
|---|---|---|
| Swashbuckle.AspNetCore.Filters |  | 一些有用的 Swashbuckle.AspNetCore 过滤器，用于添加额外的文档，例如请求和响应示例、授权信息等。有关更多详细信息，请参阅其 README。 |
| Unchase.Swashbuckle.AspNetCore.Extensions |  | 一些有用的扩展（过滤器），用于添加额外的文档，例如隐藏未接受角色的 PathItems，修复客户端代码生成的枚举等。有关更多详细信息，请参阅其 README。 |
| MicroElements.Swashbuckle.FluentValidation |  | 使用 FluentValidation 规则而不是 ComponentModel 属性来增强生成的 OpenAPI 模式。 |
| MMLib.SwaggerForOcelot |  | 直接在 Ocelot API Gateway 上聚合微服务的文档。 |
Configuration and Customization
上述步骤将帮助您以最小的设置快速上手。然而，Swashbuckle.AspNetCore 提供了大量的灵活性，以便您按需进行自定义。
请查看下表以获取所有可能的配置选项的完整列表。
| 组件 | 配置与自定义 |
|---|---|
| Swashbuckle.AspNetCore.Swagger | 更改 OpenAPI JSON 端点的路径 |
| 使用请求上下文修改 OpenAPI | |
| 以 3.1 格式序列化 OpenAPI JSON | |
| 以 2.0 格式序列化 Swagger JSON | |
| 处理虚拟目录和反向代理 | |
| 自定义 OpenAPI 文档的序列化方式 | |
| Swashbuckle.AspNetCore.SwaggerGen | 分配显式 OperationIds |
| 列出操作响应 | |
| 标记必需参数和模式属性 | |
| 处理表单和文件上传 | |
| 处理文件下载 | |
| 包含来自 XML 注释的描述 | |
| 提供全局 API 元数据 | |
| 生成多个 OpenAPI 文档 | |
| 省略已弃用的操作和/或模式属性 | |
| 省略任意操作 | |
| 自定义操作标签（例如用于 UI 分组） | |
| 更改操作排序（例如用于 UI 排序） | |
| 自定义 Schema Ids | |
| 为特定类型覆盖 Schema | |
| 使用操作、Schema 和文档过滤器扩展生成器 | |
| 添加安全定义和要求 | |
| 为 Bearer 认证添加安全定义和要求 | |
| 继承和多态 | |
| Swashbuckle.AspNetCore.SwaggerUI | 更改 UI 的相对路径 |
| 更改文档标题 | |
| 更改 CSS 或 JS 路径 | |
| 列出多个 OpenAPI 文档 | |
| 应用 swagger-ui 参数 | |
| 注入自定义 JavaScript | |
| 注入自定义 CSS | |
| 自定义 index.html | |
| 启用 OAuth2.0 流程 | |
| 使用客户端请求和响应拦截器 | |
| Swashbuckle.AspNetCore.Annotations | 安装并启用 Annotations |
| 丰富操作元数据 | |
| 丰富响应元数据 | |
| 丰富参数元数据 | |
| 丰富请求体元数据 | |
| 丰富模式元数据 | |
| 将模式过滤器应用于特定类型 | |
| 添加标签元数据 | |
| Swashbuckle.AspNetCore.Cli | 直接从启动程序集获取 OpenAPI |
| 使用自定义主机配置使用 CLI 工具 | |
| Swashbuckle.AspNetCore.ReDoc | 更改 UI 的相对路径 |
| 更改文档标题 | |
| 应用 Redoc 参数 | |
| 注入自定义 CSS | |
| 自定义 index.html |