新版本Swashbuckleswagger组件中的坑

新版本 Swashbuckle swagger 组件中的 Servers 坑

Intro

上周做了公司的项目升级&＃xff0c;从 2.2 更新到 3.1&＃xff0c; swagger 直接更新到了最新&＃xff0c;swagger 用的组件是 Swashbuckle.AspNetCore&＃xff0c;然后遇到一个 swagger 的问题&＃xff0c; 在本地测试是没问题的&＃xff0c;但是部署在测试环境之后就会有问题&＃xff0c;主要是 swagger 界面会多一个 servers 的选项&＃xff0c;可能会导致 swagger 不能正常使用&＃xff0c;下面详细介绍一下

Swagger "bug" reproduce

大概的问题是这样的&＃xff0c;在本地环境是好的&＃xff0c;在测试环境部署是有问题&＃xff0c;测试环境部署之后的 swagger 界面大致如下&＃xff1a;

很明显这个 servers 是有问题的&＃xff0c;我们实际访问的地址是 https://testserver/swagger 这样的地址&＃xff0c;但是 swagger 内部拼出来的 server 地址和实际访问的地址是不符的&＃xff0c;swagger 生成的 open api 文档里也会有一个 servers 的属性&＃xff0c;示例如下&＃xff1a;

这会导致我们使用 swagger 调试 API 的时候会走一个错误的 server 地址&＃xff0c;实际请求的地址是 sever 地址加上 api path&＃xff0c;可以看一个示例

Dig the Source

Swashbuckle.AspNetCore 是开源的&＃xff0c;我们就是扒一扒它的实现源码吧&＃xff0c;我们用的是 5.6.3 版本&＃xff0c;直接看 5.6.3 tag 对应的代码&＃xff0c;可以找到 swagger 的中间件

https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v5.6.3/src/Swashbuckle.AspNetCore.Swagger/SwaggerMiddleware.cs

在这里我们可以看到&＃xff0c;再返回给客户端之前 open api 文档响应之前我们是可以看到&＃xff0c;是会经过 PreSerializeFilters 处理的&＃xff0c;我们再详细看一下 swaggerProvider.GetSwagger 的实现

实现代码在这里&＃xff08;可以通过服务注册找到对应的实现&＃xff0c;也可以直接找对应接口的实现&＃xff09;

https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v5.6.3/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs#L31

二者结合来看&＃xff0c;servers 会根据用户请求来获取一个 server 地址&＃xff0c;而当有 X-Forwarded-Host 请求头的时候如果没有按照 swagger 指定的规则这样进行请求头的转发就会导致有问题&＃xff0c;而我们的测试环境也正是因为如此&＃xff0c;测试环境有一层 LB&＃xff0c;经过 LB 转发了 X-Forwarded-Host 和 X-Forwarded-Proto 请求头&＃xff0c;但是没有转发 X-Forwarded-Port 所以经过 swagger 的处理之后&＃xff0c;就从 https://testserver 变成了 https://testserver:80 这样

private string GetHostOrNullFromRequest(HttpRequest request)
{if (!request.Headers.TryGetValue("X-Forwarded-Host", out StringValues forwardedHost))return null;var hostBuilder &＃61; new UriBuilder($"http://{forwardedHost[0]}");if (request.Headers.TryGetValue("X-Forwarded-Proto", out StringValues forwardedProto))hostBuilder.Scheme &＃61; forwardedProto[0];if (request.Headers.TryGetValue("X-Forwarded-Port", out StringValues forwardedPort))hostBuilder.Port &＃61; int.Parse(forwardedPort[0]);return hostBuilder.Uri.ToString().Trim(&＃39;/&＃39;);
}private string GetBasePathOrNullFromRequest(HttpRequest request)
{var pathBuilder &＃61; new StringBuilder();if (request.Headers.TryGetValue("X-Forwarded-Prefix", out StringValues forwardedPrefix))pathBuilder.Append(forwardedPrefix[0].TrimEnd(&＃39;/&＃39;));if (request.PathBase.HasValue)pathBuilder.Append(request.PathBase.Value.TrimEnd(&＃39;/&＃39;));return (pathBuilder.Length > 0)? pathBuilder.ToString(): null;
}


解决方案

从上面的源码中基本就可以分析出问题的原因来&＃xff0c;解决的办法我觉得有下面几种&＃xff1a;

1. LB 转发的时候带上 X-Forwarded-Port 请求头&＃xff0c;转发原始请求的端口号&＃xff08;需要 LB 转发自己能够控制&＃xff0c;我们如果要配置还需要让 DevOps 的童鞋帮忙弄&＃xff0c;如果完全是自己控制的就比较方便【推荐】&＃xff09;

2. 在使用 Swagger 中间件之前把 X-Forwarded-Port 请求头设置为 443&＃xff08;不够灵活&＃xff0c;如果访问 LB 是 http 或者有特别的端口号就会有问题&＃xff09;

3. 在使用 swagger 中间件之前把 X-Forwarded-Host 请求头移除掉&＃xff0c;这样就不会有 servers 这个属性了(感觉不够优雅)

4. 注册一个 PreSerializeFilter 把 Servers 清空&＃xff0c;实现代码如下&＃xff08;【推荐】&＃xff0c;没有 servers 属性的时候完全按请求 swagger 的 baseUrl 来作为 api 的前缀&＃xff0c;示例代码如下&＃xff09;

app.UseSwagger(c &＃61;>
{c.PreSerializeFilters.Add((doc, _) &＃61;>{doc.Servers?.Clear();});
});


更新之后就没有 servers 属性了&＃xff0c;和之前的版本保持一致了

More

我们使用的是 5.6.3 版本&＃xff0c;应该从 5.6.0 开始都有这个问题&＃xff0c;如果遇到了这个问题不要慌哈&＃xff0c;参考上面的解决方案即可

我觉得 swagger 这样的实现方式不太友好&＃xff0c;更好的实现应该结合微软的 ForwardHeaders 中间件来实现&＃xff0c;Swagger 组件作者表示已经有计划&＃xff0c;打算在 6.0 的时候更新结合微软的中间件来实现&＃xff0c;详细可以参考 Github 上的 Issue https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1814

Reference

• https://github.com/domaindrivendev/Swashbuckle.AspNetCore

• https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v5.6.3/src/Swashbuckle.AspNetCore.Swagger/SwaggerMiddleware.cs

• https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v5.6.3/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs#L31

• https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1814