Swashbuckle.AspNetCore中实现按需绑定API文档的方法

在ASP.NET Core开发中，Swashbuckle.AspNetCore是生成API文档的常用工具。但在实际项目中，我们经常遇到只需要为特定程序集生成文档的需求。本文将介绍几种在Swashbuckle.AspNetCore中实现选择性文档绑定的技术方案。

方案一：使用ApiExplorerSettings分组

最直接的方式是通过ApiExplorerSettings特性对控制器进行分组标记：

// 在程序集1的控制器上
[ApiExplorerSettings(GroupName = "WebApi")]
public class WebApiController : ControllerBase
{
    // ...
}

// 在程序集2的控制器上
[ApiExplorerSettings(GroupName = "InternalApi")]
public class InternalController : ControllerBase
{
    // ...
}

然后在Swagger配置中，可以分别为不同分组创建文档：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("webapi", new OpenApiInfo { Title = "Web API", Version = "v1" });
    c.SwaggerDoc("internalapi", new OpenApiInfo { Title = "Internal API", Version = "v1" });
});

如果只需要公开某个程序集的API，可以只为特定分组配置UI：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/webapi/swagger.json", "Public Web API");
});

方案二：完全隐藏特定程序集

对于完全不希望出现在文档中的程序集，可以在控制器或方法上使用IgnoreApi标记：

[ApiExplorerSettings(IgnoreApi = true)]
public class InternalController : ControllerBase
{
    // 这个控制器不会出现在任何文档中
}

方案三：使用Schema过滤器精细控制

对于更复杂的需求，可以实现ISchemaFilter接口来自定义文档生成逻辑：

public class CustomSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 根据类型所在的程序集决定是否包含在文档中
        if (context.Type.Assembly.GetName().Name == "Project.Web.Api")
        {
            // 自定义处理逻辑
        }
    }
}

然后在Swagger配置中注册这个过滤器：

services.AddSwaggerGen(c =>
{
    c.SchemaFilter<CustomSchemaFilter>();
});

最佳实践建议

1. 明确文档范围：在项目初期就规划好哪些API需要公开文档

2. 保持一致性：为不同程序集建立明确的命名规范，便于过滤

3. 考虑安全性：确保内部API不会意外暴露在公开文档中

4. 文档版本控制：结合API版本控制策略，为不同程序集设置适当的版本号

通过以上方法，开发者可以灵活控制Swashbuckle.AspNetCore生成的文档范围，确保只公开必要的API接口，同时保持内部API的私密性。