企业官网建设流程全解析

1. 问题现场还原与根因定位

1.1 这个报错到底在抱怨什么

Unable to infer base url和Unable to render this definition这两个提示，几乎可以算是 Spring Boot 项目接入 Swagger3（也就是 springdoc-openapi）之后最常见的“见面礼”。前者通常出现在 Swagger UI 页面的顶部横幅里，页面能打开，但下拉框里的分组是空的，或者干脆连接口列表都渲染不出来；后者则更彻底一点，页面直接白屏，中间一行红字告诉你 definition 渲染失败。很多人第一次遇到的时候会本能地怀疑依赖版本不对，反复升级降级springdoc-openapi-ui，折腾半天发现问题照旧——因为真正的凶手大概率不在 Swagger 本身，而在你自己写的那个HandlerInterceptor上。

先把结论摆在前面：springdoc-openapi 在启动和运行时，会通过一组固定的 HTTP 端点向服务端索取文档元数据，这些端点的路径是硬编码在SwaggerWelcomeWebMvc、OpenApiWebMvcResource这些类里的。只要你的拦截器对/v3/api-docs、/v3/api-docs/swagger-config、/swagger-ui/**这些路径做了登录校验、Token 校验、或者统一返回了自定义的错误 JSON，Swagger UI 拿不到它期待的响应体，就会在浏览器端抛出这两个错误。换句话说，这不是 Swagger 坏了，是你把它的“口粮”给截了。

我第一次踩这个坑是在一个前后端分离的项目里，后端加了统一的 JWT 拦截器，对所有非白名单路径做鉴权。Swagger UI 的静态资源能加载，但/v3/api-docs/swagger-config返回的是{"code":401,"msg":"未登录"}，于是页面顶部就顶着那行 base url 推断失败的提示。当时查了两小时，最后发现只需要在拦截器的addPathPatterns里排除掉那几个路径就完事了。这个经历让我意识到，这两个错误的本质是“拦截器与文档端点抢路由”，而不是 Swagger 的配置问题。

1.2 三个关键端点的职责划分

要理解为什么会被拦截，得先搞清楚 springdoc-openapi 到底请求了哪些地址。很多人只知道/v3/api-docs，其实完整的链路包含三个角色。

这张表建议直接存进你的排查笔记。实际排查时，打开浏览器开发者工具的 Network 面板，刷新 Swagger 页面，看这几个请求的响应状态码和响应体。如果/v3/api-docs/swagger-config返回 200 但内容是{"code":401}之类的自定义结构，那基本可以锁定是拦截器把它当业务接口处理了。如果返回的是 302 重定向到登录页，那说明拦截器做了重定向而非直接返回 JSON，这种情况下 UI 会尝试跟随重定向，最终拿到的是一段 HTML，解析 JSON 时失败，报的也是 base url 推断错误。

1.3 为什么拦截器会“误伤”文档端点

默认情况下，Spring MVC 的拦截器是全局生效的，只要你在WebMvcConfigurer的addInterceptors里注册了它，并且addPathPatterns("/**")，那它就会拦截一切进入 DispatcherServlet 的请求，包括 springdoc 注册的那些 handler。这里有一个容易被忽略的细节：springdoc 的端点是通过@RestController或者RequestMappingHandlerMapping动态注册的，它们和你的业务 Controller 走的是同一套请求映射流程，所以拦截器天然会命中它们。

有些人会想：“那我用@Bean注册的HandlerInterceptor不就是为了统一鉴权吗？”问题在于，统一鉴权的前提是“所有需要鉴权的接口”，而文档端点在大多数开发环境里恰恰是不需要鉴权的。把不需要鉴权和需要鉴权的接口混在同一套规则里，就必然要显式排除。更麻烦的是，有些团队在拦截器里直接读取HttpServletRequest的 header 判断 token，token 缺失时直接response.getWriter().write(...)并把响应标记为已完成，这种行为会彻底切断 springdoc 端点的正常返回链路。

还有一个隐蔽的坑：如果你在拦截器里调用了response.sendRedirect()或者返回了false但没写响应体，浏览器会收到一个空响应或重定向，Swagger UI 的 JS 代码在解析时会抛出异常。所以排查这个问题，光看后端日志有时不够，必须结合浏览器 Network 面板一起看。

2. 核心方案选型与配置思路

2.1 主流解决路径的横向对比

遇到这个问题，网上的方案五花八门，但归纳起来其实就是四类思路。我在不同项目里都试过，每种都有适用场景，不能一概而论。

第一种是拦截器路径排除，也就是在注册拦截器时用excludePathPatterns把文档相关路径排除掉。这是最直接、侵入性最小的方案，适合绝大多数中小项目。第二种是在拦截器内部判断路径，通过request.getRequestURI()判断当前请求是否属于文档端点，是则直接放行。第三种是调整文档端点的前缀，把 springdoc 的默认路径改成一个业务拦截器不覆盖的路径，比如写成/api-docs之外的/doc-internal。第四种是给文档端点单独开一个端口，通过management.server.port或自定义 Servlet 容器实现，适合对安全隔离要求高的场景。

我的建议是：开发和测试环境用第一种，简单粗暴且不容易出错；生产环境要么关闭 Swagger，要么用第二种加开关控制，不要图省事在生产也放开所有文档端点。这里顺便提一句，很多团队会在生产环境用springdoc.api-docs.enabled=false和springdoc.swagger-ui.enabled=false直接关掉文档，这样拦截器爱怎么拦都无所谓，因为端点根本不存在。

2.2 为什么排除路径比改路径更优先

有人可能会问，既然改前缀也能解决，为什么不直接改前缀，一劳永逸？这里面有个现实考量：改前缀虽然能让当前项目的拦截器不再命中，但一旦项目里有其他组件硬编码了/v3/api-docs，比如前端团队自己写的接口调试页面、API 网关的文档聚合配置、或者 CI 流程里的文档校验脚本，就会连锁失效。我在一个项目里就遇到过，网关层聚合了多个微服务的 Swagger 文档，结果其中一个服务改了前缀，网关那边直接拉不到文档，排查了好久才定位到。

而excludePathPatterns是纯后端改动，影响面可控，且语义清晰——它明确表达了“这些路径不走我的业务鉴权”。从可维护性角度看，这种显式排除比隐式改路径更容易被后来接手的人理解。所以除非你有明确的安全诉求需要隐藏默认路径，否则优先用排除。

2.3 拦截器注册的正确姿势与常见误区

在 Spring Boot 里注册拦截器的标准写法是实现WebMvcConfigurer接口，重写addInterceptors方法，然后往InterceptorRegistry里添加。这里有几个细节值得展开说。

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Autowired private AuthInterceptor authInterceptor; @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(authInterceptor) .addPathPatterns("/**") .excludePathPatterns( "/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/doc.html", "/favicon.ico" ); } }

这段代码看起来很普通，但有几个坑必须点出来。第一，/v3/api-docs/**和/v3/api-docs的区别。Spring 的路径匹配里，/**能匹配多级路径，但/v3/api-docs这个端点本身是单级路径，/v3/api-docs/swagger-config是两级。如果你只写/v3/api-docs/**，在较老的 Spring 版本里可能匹配不到/v3/api-docs本身。稳妥的做法是两个都写，或者直接用/v3/api-docs/**配合/v3/api-docs一起排除。我在 Spring Boot 2.3 的项目里实测过，只写/v3/api-docs/**时，某些版本确实会漏掉裸路径。

第二，/swagger-ui/**和/swagger-ui.html要分开写。swagger-ui.html是 Springfox 时代的入口，springdoc-openapi 默认的 UI 入口是/swagger-ui/index.html，但为了兼容，很多人还是会把swagger-ui.html加上。第三，/webjars/**千万别漏，Swagger UI 的 JS 和 CSS 是通过 webjars 依赖提供的，漏掉这个路径会导致页面样式全无，虽然不会报那两个错，但体验极差。

注意：如果你用的是 Spring Security 而不是自定义拦截器，情况会略有不同。Spring Security 的过滤器链在 DispatcherServlet 之前执行，需要在WebSecurityConfigurerAdapter或 SecurityFilterChain 里对文档路径放行，否则请求根本到不了拦截器这一层。两套机制的排除写法经常被人混淆。

3. 实操配置全流程与代码拆解

3.1 从零搭建一个可复现的报错环境

为了把这套排查逻辑讲透，我先带你复现一次问题。环境是 Spring Boot 2.7.x 加 springdoc-openapi 1.6.x，JDK 8 或 11 都行。

先在pom.xml里引入依赖，注意 springdoc-openapi 的版本要和 Spring Boot 大版本匹配。Spring Boot 2.x 用 1.x 系列，Spring Boot 3.x 用 2.x 系列，这个对应关系弄错了，会出现一堆莫名其妙的问题。

<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.15</version> </dependency>

然后写一个最简单的鉴权拦截器，故意不做任何路径排除，制造问题现场：

@Component public class AuthInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token = request.getHeader("Authorization"); if (token == null || token.isEmpty()) { response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.setContentType("application/json;charset=UTF-8"); response.getWriter().write("{\"code\":401,\"msg\":\"未登录\"}"); return false; } return true; } }

注册时不排除任何路径：

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Autowired private AuthInterceptor authInterceptor; @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(authInterceptor).addPathPatterns("/**"); } }

启动项目，访问http://localhost:8080/swagger-ui/index.html，你就会看到页面顶部出现Unable to infer base url的提示，或者接口列表完全是空的。此时打开 Network 面板，能看到/v3/api-docs/swagger-config返回了 401 和那段自定义 JSON。问题复现成功。

3.2 按端点逐个放行的最小改动方案

复现之后，修复其实很简单，就是在excludePathPatterns里补上文档路径。但我不建议只补一个/v3/api-docs/**就完事，而是按端点语义分组排除，这样后续维护时一眼能看懂。

@Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(authInterceptor) .addPathPatterns("/**") .excludePathPatterns( // springdoc 文档元数据端点 "/v3/api-docs", "/v3/api-docs/**", // Swagger UI 静态资源 "/swagger-ui.html", "/swagger-ui/**", // webjars 依赖的 JS/CSS "/webjars/**", // 兼容旧版与第三方 UI "/swagger-resources/**", "/doc.html", // 浏览器默认请求 "/favicon.ico" ); }

改完重启，再次访问 UI，那两个错误应该都消失了。这里我想强调一点：只排除/v3/api-docs/**有时候还不够，因为swagger-config这个端点在某些版本的实现里走的是另一个 handler。我遇到过只排除/v3/api-docs/**后，/v3/api-docs/swagger-config依然被拦的情况，所以显式写出裸路径是更稳妥的做法。

3.3 如果不想改拦截器：在拦截器内部做 URI 判断

有些团队因为架构原因，不方便修改拦截器的注册配置，比如拦截器是通过 starter 自动装配进来的，改不了别人写的配置类。这种情况下，可以在拦截器内部做判断，属于文档端点的请求直接放行。

@Component public class AuthInterceptor implements HandlerInterceptor { private static final List<String> WHITE_LIST = Arrays.asList( "/v3/api-docs", "/swagger-ui", "/swagger-resources", "/webjars", "/doc.html" ); @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String uri = request.getRequestURI(); for (String prefix : WHITE_LIST) { if (uri.startsWith(prefix)) { return true; } } // 下面是正常的鉴权逻辑 String token = request.getHeader("Authorization"); if (token == null || token.isEmpty()) { response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.setContentType("application/json;charset=UTF-8"); response.getWriter().write("{\"code\":401,\"msg\":\"未登录\"}"); return false; } return true; } }

这种写法的好处是放行逻辑集中在一处，不依赖外部的路径排除配置；坏处是白名单和业务代码耦合，未来如果 springdoc 换了默认路径，还得改代码。我的经验是，如果项目里拦截器不多，优先用配置排除；如果拦截器是通过框架统一管理的，那就只能走代码判断这条路。另外要注意，request.getRequestURI()返回的路径可能带 context-path，如果项目配置了server.servlet.context-path，判断时需要把它考虑进去，否则前缀匹配会失败。

3.4 生产环境的安全收口与开关设计

开发环境放行文档没问题，但生产环境直接放行所有文档端点，等于把你的接口结构、参数定义全暴露了。我的做法是用配置开关把文档的启用与鉴权分离，通过 profile 控制。

# application-dev.yml springdoc: api-docs: enabled: true swagger-ui: enabled: true # application-prod.yml springdoc: api-docs: enabled: false swagger-ui: enabled: false

配合拦截器里的条件放行，可以用@Value注入环境标记，生产环境即使有人误加了白名单，文档端点也是关闭的，双重保险。

@Value("${springdoc.api-docs.enabled:false}") private boolean apiDocsEnabled;

然后在拦截器里判断，如果文档端点未启用，就走正常鉴权流程，不给任何放行机会。这套组合我在几个对外服务上都用过，既保证了开发效率，又堵住了生产泄露的口子。还有一个细节：如果你用了网关聚合文档，生产环境的聚合端点也需要单独处理，不能简单地把所有服务的文档都放开。

注意：关闭文档端点后，如果拦截器白名单还残留着/v3/api-docs/**，虽然端点不存在了不会造成泄露，但会让后来接手的人产生困惑。建议关闭时同步清理白名单，保持配置的一致性。