Swagger UI 仅为用户暴露已授权终结点

前言

当需要在生产环境中提供 Swagger UI 时，我们可以通过身份验证，控制只有授权用户才能访问 Swagger UI 页面。

但是我们希望更进一步，每个用户只能看到授权给他的终结点，而不会暴露其他未授权终结点信息。

比如， API 提供了方法 A 和 方法 B，而对于用户 zhangsan 来说，他在 Swagger UI 页面只能看到方法 A 的说明，而不会知道方法 B 的存在。

思路

Swagger UI 页面展示的数据来源，其实是/swagger/v1/swagger.json文件：

app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApplication1 v1"));

而swagger.json的格式是遵循 OpenAPI 规范的。

其中，paths定义了 API 的所有终结点：

那么，只需要保证swagger.json包含的paths仅定义了授权接口的终结点即可。

虽然我们不能控制swagger.json文件的生成，但是我们可以控制它如何输出到响应啊！

我们可以定义一个Middleware，实现如下功能：

1. 判断当前请求是否swagger.json

2. 如果是，截获原始响应，即swagger.json文件内容

3. 创建一个新的 json 文件，遍历swagger.json所有 JSON 结点，写入到新 json 文件中

4. 如果当前节点是paths节点下的子节点，先判断子节点名称是否是授权终结点，是则写入，否则跳过

5. 将新 json 文件输出到响应中

实现

SwaggerEndpointsFilterMiddleware实现代码如下：

public class SwaggerEndpointsFilterMiddleware
{
    private readonly RequestDelegate _next;

    public SwaggerEndpointsFilterMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task Invoke(HttpContext httpContext)
    {
        if (httpContext.Request.Path.Value != null && httpContext.Request.Path.HasValue &&
            httpContext.Request.Path.Value.Contains("swagger.json", StringComparison.InvariantCultureIgnoreCase))
        {
            var originalStream = httpContext.Response.Body;
            using (var memoryStream = new MemoryStream())
            {
                //截获原始响应，将响应内容写入 MemoryStream
                httpContext.Response.Body = memoryStream;

                await _next(httpContext);

                //获取当前用户可访问的 Endpoints
                var validEndpoints = GetValidEndpoints(httpContext.Request);

                memoryStream.Position = 0;
                using (var sr = new StreamReader(memoryStream))
                {
                    //将修改过的 json 写入响应 
                    await originalStream.WriteAsync(CreateSwaggerJson(sr.ReadToEnd(), validEndpoints));
                }
                
                httpContext.Response.Body = originalStream;
                return;
            }
        }

        await _next(httpContext);
    }
}

关键代码在CreateSwaggerJson:

private byte[] CreateSwaggerJson(string json, IEnumerable<string> validEndpoints)
{
    using (var memoryStream = new MemoryStream())
    {
        using (var utf8JsonWriter = new Utf8JsonWriter(memoryStream))
        {
            using (var jsonDocument = JsonDocument.Parse(json))
            {
                utf8JsonWriter.WriteStartObject();

                foreach (var element in jsonDocument.RootElement.EnumerateObject())
                {
                    if (element.Name == "paths")
                    {
                        utf8JsonWriter.WritePropertyName(element.Name);
                        utf8JsonWriter.WriteStartObject();

                        //遍历 paths 子节点，检查 Endpoint 是否已授权
                        foreach (var endpoint in element.Value.EnumerateObject())
                        {
                            if (validEndpoints.Contains(endpoint.Name))
                            {
                                endpoint.WriteTo(utf8JsonWriter);
                            }
                        }

                        utf8JsonWriter.WriteEndObject();
                    }
                    else
                    {
                        element.WriteTo(utf8JsonWriter);
                    }
                }

                utf8JsonWriter.WriteEndObject();
            }
        }

        return memoryStream.ToArray();
    }
}

最后，修改 Startup.cs:

app.UseMiddleware<SwaggerEndpointsFilterMiddleware>();

app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApplication1 v1"));

结论

今天，我们通过 Middleware 拦截swagger.json的输出，实现了 Swagger UI 仅为用户暴露已授权终结点。

添加微信号【MyIO666】，邀你加入技术交流群