Swashbuckle.AspNetCore 配置与自定义指南

Swashbuckle.AspNetCore 配置与自定义指南

Swashbuckle.AspNetCore Swashbuckle.AspNetCore：这是一个用于ASP.NET Core的Swagger文档生成器，适合为RESTful API生成API文档。特点包括自动生成API文档、支持多种输出格式（如Markdown、HTML等）、与ASP.NET Core集成良好等。 项目地址: https://gitcode.com/gh_mirrors/sw/Swashbuckle.AspNetCore

前言

Swashbuckle.AspNetCore 是一个强大的工具，它能自动为 ASP.NET Core Web API 生成 Swagger/OpenAPI 文档。本文将深入探讨如何配置和自定义 Swagger 文档的生成过程，帮助开发者根据项目需求进行灵活调整。

基础配置

修改 Swagger JSON 端点路径

默认情况下，Swagger JSON 文档会暴露在 /swagger/{documentName}/swagger.json 路径下。但在实际项目中，我们可能需要修改这个路径以满足特定的路由需求。

app.UseSwagger(options =>
{
    options.RouteTemplate = "api-docs/{documentName}/swagger.json";
});

重要提示：自定义路径必须包含 {documentName} 参数，因为 Swashbuckle 支持多文档生成，需要通过文档名称来区分不同的 API 版本或模块。

如果同时使用了 SwaggerUI 中间件，记得同步更新其配置以匹配新的端点路径：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/api-docs/v1/swagger.json", "My API V1");
});

高级自定义

基于请求上下文修改 Swagger

在某些场景下，我们可能需要根据当前请求动态调整 Swagger 文档内容。Swashbuckle 提供了 PreSerializeFilters 机制来实现这一需求。

app.UseSwagger(options =>
{
    options.PreSerializeFilters.Add((swagger, httpReq) =>
    {
        swagger.Servers = [new OpenApiServer { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" }];
    });
});

这个功能非常强大，可以实现：

• 根据请求头动态设置服务器地址
• 基于用户权限过滤 API 操作
• 根据会话信息调整文档内容

选择 OpenAPI 规范版本

Swashbuckle 默认生成 OpenAPI 3.0 规范的文档，但也支持向后兼容的 Swagger 2.0 格式：

app.UseSwagger(options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi2_0;
});

适用场景：当需要与仅支持 Swagger 2.0 的工具链集成时，这个选项就非常有价值。

部署相关配置

虚拟目录和反向代理处理

在虚拟目录或反向代理环境下，绝对 URL 可能会引发问题。Swashbuckle 推荐使用相对 URL 来确保在各种部署场景下都能正常工作。

app.UseSwaggerUI(options =>
{
    options.RoutePrefix = "swagger";
    options.SwaggerEndpoint("v1/swagger.json", "My API V1");
});

最佳实践：避免使用根路径相对链接（如 /swagger/v1/swagger.json），而是采用页面相对路径，这样可以确保在 IIS 虚拟目录或代理环境下也能正常工作。

序列化自定义

自定义 OpenAPI 文档序列化

Swashbuckle 默认使用内置的序列化逻辑，但我们可以通过实现 ISwaggerDocumentSerializer 接口来自定义序列化过程。

services.ConfigureSwagger(options =>
{
    options.SetCustomDocumentSerializer<CustomDocumentSerializer>();
});

实现要点：

1. 自定义序列化器必须实现 ISwaggerDocumentSerializer 接口
2. 如果使用命令行工具生成 OpenAPI 规范文件，必须在服务集合中配置
3. 否则，也可以在应用主机中配置

总结

通过 Swashbuckle.AspNetCore 的丰富配置选项，开发者可以灵活地调整 Swagger 文档的生成和展示方式，满足各种项目需求。从基本的路径修改到高级的动态文档生成，这些功能使得 API 文档能够更好地适应不同的开发和生产环境。

掌握这些配置技巧，将帮助您创建更加专业、适应性更强的 API 文档系统，提升开发体验和 API 的可维护性。

Swashbuckle.AspNetCore Swashbuckle.AspNetCore：这是一个用于ASP.NET Core的Swagger文档生成器，适合为RESTful API生成API文档。特点包括自动生成API文档、支持多种输出格式（如Markdown、HTML等）、与ASP.NET Core集成良好等。 项目地址: https://gitcode.com/gh_mirrors/sw/Swashbuckle.AspNetCore