新版本 swagger 组件中 Servers 的 坑

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

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

新版本 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-Host 和 X-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

便宜好用的国外VPS推荐