使用NSwag拆分生成公开/内部多份OpenAPI文档的方案咨询

实现方案 #

核心逻辑是通过路由前缀匹配筛选接口，无需绑定控制器命名规则，同时原生支持API版本能力：

1. 实现通用路由前缀筛选处理器

public class RoutePrefixFilterProcessor : IOperationProcessor
{
    private readonly string _matchPrefix;

    public RoutePrefixFilterProcessor(string matchPrefix)
    {
        _matchPrefix = matchPrefix.Trim('/');
    }

    public bool Process(OperationProcessorContext context)
    {
        var apiRoute = context.ApiDescription.RelativePath?.Trim('/');
        if (string.IsNullOrEmpty(apiRoute)) 
            return false;
        return apiRoute.StartsWith(_matchPrefix, StringComparison.OrdinalIgnoreCase);
    }
}

2. 注册两份OpenAPI文档

// 公开API文档配置
services.AddOpenApiDocument(settings =>
{
    settings.DocumentName = "public";
    settings.Title = "公开接口文档 v1";
    // 仅匹配/api/v1/前缀的接口
    settings.OperationProcessors.Add(new RoutePrefixFilterProcessor("/api/v1/"));
    settings.SchemaNameGenerator = new NSwagNestedNameGenerator();
    // 对接ASP.NET Core API版本控制时添加，指定对应版本组即可保留版本支持
    // settings.ApiGroupNames = new[] { "v1" };
});

// 内部管理API文档配置
services.AddOpenApiDocument(settings =>
{
    settings.DocumentName = "internal";
    settings.Title = "内部管理接口文档 v1";
    // 仅匹配/admin/api/v1/前缀的接口
    settings.OperationProcessors.Add(new RoutePrefixFilterProcessor("/admin/api/v1/"));
    settings.SchemaNameGenerator = new NSwagNestedNameGenerator();
    // 多版本支持可传入多个版本组名
    // settings.ApiGroupNames = new[] { "v1", "v2" };
});

3. 配置Swagger中间件

// 公开文档中间件
app.UseOpenApi(settings =>
{
    settings.DocumentName = "public";
    settings.Path = "/swagger/public/v1.json";
});
app.UseSwaggerUi3(settings =>
{
    settings.Path = "/swagger";
    settings.DocumentPath = "/swagger/public/v1.json";
});

// 内部文档中间件
app.UseOpenApi(settings =>
{
    settings.DocumentName = "internal";
    settings.Path = "/swagger-internal/internal/v1.json";
});
app.UseSwaggerUi3(settings =>
{
    settings.Path = "/swagger-internal";
    settings.DocumentPath = "/swagger-internal/internal/v1.json";
});

额外优化

可在内部文档的中间件层增加权限校验逻辑，仅允许授权的管理员访问内部接口文档，避免接口信息泄露。

内容的提问来源于stack exchange，提问作者Angius