集成springdoc-openapi Swagger UI报无有效version字段问题

项目集成springdoc-openapi-ui:1.6.9后，访问http://127.0.0.1:11014/swagger-ui/index.html页面抛出如下错误：

Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

经排查，正常场景下OpenAPI文档接口返回顶层带openapi: 3.0.1字段的标准JSON对象，当前项目该接口返回的是被转义的JSON字符串，无法被Swagger UI正常解析。

springdoc内置的文档接口返回值被项目全局响应处理逻辑二次序列化：原本的OpenAPI结构化对象被提前转成JSON字符串后再次写入响应，Swagger UI拿到字符串类型的响应后无法识别顶层的版本字段，最终触发渲染错误。

• 检查项目是否实现ResponseBodyAdvice做全局统一响应封装：这是该问题最高发的场景，全局返回值处理如果没有排除文档接口，会把所有接口返回值（包括springdoc的OpenAPI对象）都做二次包装、二次序列化。
• 检查是否自定义了Spring MVC的HttpMessageConverter：如果重写了消息转换器，且对Object类型返回值统一做字符串序列化，会导致接口返回转义后的JSON字符串。
• 检查是否存在全局过滤器、拦截器对响应体做统一包装处理，篡改了文档接口的响应格式。
• 如果项目集成了权限框架，检查是否权限逻辑对文档接口的响应做了拦截篡改。

• 给全局响应处理逻辑添加路径白名单，跳过springdoc相关路径的处理，需要排除的路径如下：

  /v3/api-docs/**
  /swagger-ui/**
  /swagger-resources/**
  

  以ResponseBodyAdvice实现类为例，在supports方法中添加路径判断逻辑，命中上述路径直接返回false不做处理：

  @Override
  public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
      ServletRequestAttributes requestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
      if (requestAttributes == null) {
          return false;
      }
      String requestPath = requestAttributes.getRequest().getRequestURI();
      // 跳过swagger文档相关接口
      if (requestPath.startsWith("/v3/api-docs") 
              || requestPath.startsWith("/swagger-ui") 
              || requestPath.startsWith("/swagger-resources")) {
          return false;
      }
      // 原有业务判断逻辑
      return true;
  }
  

• 如果是自定义HttpMessageConverter导致的问题，调整转换器的生效规则，不对OpenAPI、SwaggerResource这类springdoc内置的返回类型做字符串序列化，保留默认Jackson转换器的JSON序列化逻辑。
• 给权限框架添加白名单配置，放开上述文档路径的匿名访问权限，避免权限逻辑篡改响应内容。

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