新版本 swagger 组件中 Servers 的 坑

  • A+
所属分类:.NET技术
摘要

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


新版本 Swashbuckle swagger 组件中 Servers 的 坑

Intro

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

Swagger "bug" reproduce

大概的问题是这样的,在本地环境是好的,在测试环境部署是有问题,测试环境部署之后的 swagger 界面大致如下:

新版本 swagger 组件中 Servers 的 坑

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

新版本 swagger 组件中 Servers 的 坑

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

新版本 swagger 组件中 Servers 的 坑

Dig the Source

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

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

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

实现代码在这里(可以通过服务注册找到对应的实现,也可以直接找对应接口的实现)

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

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

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

解决方案

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

  1. LB 转发的时候带上 X-Forwarded-Port 请求头,转发原始请求的端口号(需要 LB 转发自己能够控制,我们如果要配置还需要让 DevOps 的童鞋帮忙弄,如果完全是自己控制的就比较方便【推荐】)
  2. 在使用 Swagger 中间件之前把 X-Forwarded-Port 请求头设置为 443(不够灵活,如果访问 LB 是 http 或者有特别的端口号就会有问题)
  3. 在使用 swagger 中间件之前把 X-Forwarded-Host 请求头移除掉,这样就不会有 servers 这个属性了(感觉不够优雅)
  4. 注册一个 PreSerializeFilter 把 Servers 清空,实现代码如下(【推荐】,没有 servers 属性的时候完全按请求 swagger 的 baseUrl 来作为 api 的前缀,示例代码如下)
app.UseSwagger(c => {     c.PreSerializeFilters.Add((doc, _) =>     {         doc.Servers?.Clear();     }); }); 

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

More

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

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

Reference