常见问题

先检查 Spring Boot、Spring Framework 与 SpringDoc 的版本组合。 LiteWebJarsResourceResolver 属于 Spring Framework 6.2；使用较新 SpringDoc、但宿主仍加载旧版 Spring Web 时，可能出现该类缺失。Boot 低于 3.4 的项目尤其需要检查。

当前仓库 Demo 使用以下组合，便于对照；这不是全部兼容版本的清单：

1. 确认实际运行的 JDK 为 17+，并查看宿主生效的 Boot 版本。
2. Boot 3 使用兼容的 SpringDoc 2.x，Boot 4 使用 SpringDoc 3.x；同一工程内不要混用两个主版本。
3. 检查传递依赖，排除旧 SpringDoc、旧 Swagger Starter 或手动锁定的 Spring Framework 版本。

mvn dependency:tree '-Dincludes=org.springframework.boot:*,org.springframework:*,org.springdoc:*,top.nextdoc4j:*'

NoSuchMethodError 也常见于依赖冲突，应以异常中的类和方法归属定位，不要只补一个缺失的 JAR。NextDoc4j BOM 只对齐自身模块，Boot / SpringDoc 仍由宿主管理。

继续阅读：快速开始与 BOM 示例。

依次检查功能开关、实际入口和 SpringDoc UI 依赖。 NextDoc4j 默认不开放文档。

nextdoc4j:
  enabled: true
  production: false

1. 检查当前生效的 Profile、环境变量和配置中心，确认最终值为 enabled=true、production=false。production=true 会主动返回 404，开启密码认证也不会改变这一点。
2. 默认入口是 /doc.html。配置 doc-path: /docs 后改用 /docs，旧 /doc.html 会失效；doc-path 使用单段路径。
3. 有应用上下文时带上前缀。例如 context-path=/order、doc-path=/docs 对应 /order/docs。
4. 宿主需要自行引入对应 Web 栈的 SpringDoc UI Starter。NextDoc4j Starter 中该依赖是 optional，不会自动传递给你的项目。

如果直连宿主可以打开、经过代理却是 404，再检查反向代理是否转发了入口和 /nextdoc/** 资源，而不只是业务接口。

继续阅读：基础配置 · 接入依赖。

出现 NoUniqueBeanDefinitionException 时，先看异常是否指向多个 RequestMappingHandlerMapping。业务映射、Actuator 或自定义映射可以同时存在，旧版本在只按类型获取单个 Bean 时可能发生冲突。

该问题已在 v1.4.1 修复，当前 Sa-Token 路径排除实现会遍历提供器中的多个映射器。

1. 使用包含修复的版本，并通过 nextdoc4j-bom 对齐 Starter 与插件，避免只升级了部分模块。
2. 如果仍然报错，根据异常堆栈确认是否来自其他依赖或项目自己的单 Bean 注入。
3. 使用依赖树确认运行时没有旧版 NextDoc4j 模块残留。

继续阅读：更新日志 · Sa-Token 插件。

先区分查询参数对象和 JSON 请求体。 查询 DTO 需要由 SpringDoc 展开成独立参数；这和展开 @RequestBody 的 JSON 结构是两种处理。

可以启用全局参数对象平铺：

springdoc:
  default-flat-param-object: true

也可以只对目标参数添加 org.springdoc.core.annotations.ParameterObject 注解，避免改变其他接口的文档行为：

@GetMapping("/users")
public List<UserView> list(@ParameterObject UserQuery query) {
    return userService.list(query);
}

调整后检查对应 /v3/api-docs 的 parameters 是否已生成字段。如果 JSON 请求体缺少字段，则检查 requestBody、模型 Schema、可见性与隐藏注解，参数平铺开关不负责修复请求体。

继续阅读：接口文档与数据模型。

参数显示为 arg0 / arg1 时，编译产物可能没有保留方法形参名。 在 Maven 编译插件中启用 -parameters：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <parameters>true</parameters>
    </configuration>
</plugin>

重新编译并启动应用；仅刷新页面不会改变已生成的 class 文件。IDEA 运行时也要确认采用了相同的编译配置。参数声明位于公共模块时，该模块同样需要保留形参名。

对于具体参数，还可显式声明 HTTP 参数名：

@RequestParam(name = "keyword") String keyword
@PathVariable(name = "id") Long id

上面是两种独立的参数声明示例，分别放到对应方法签名中。@Parameter(description = "关键词") 用于补充文档描述，不能代替运行时的参数绑定名称。

把文档定义和后端参数转换分开检查。 下拉候选项来自 Schema 的 enum，业务含义来自 x-nextdoc4j-enum；仅在描述中写“1 表示启用”不会生成结构化候选项。

例如界面显示 1 - 启用，真实发送值应是 1，不是整段标签。默认按枚举常量名绑定的后端可能只接受 ACTIVE；文档插件不会自动改变业务绑定规则。

继续阅读：枚举插件与转换器示例 · 三种枚举交互。

在 Network 中打开失败的 OpenAPI 请求，检查响应正文。HTTP 200 不一定是 OpenAPI JSON，也可能是登录页 HTML。

默认地址是 /v3/api-docs；如果配置了 springdoc.api-docs.path，检查自定义地址。命令行访问文档认证时，先登录保存会话 Cookie，再携带 Cookie 获取 OpenAPI。

继续阅读：文档认证与命令行示例。

开启 nextdoc4j.auth.enabled=true 而未配置密码时，当前实例会生成随机密码，并在启动日志中提示。重启后会重新生成，多实例之间不会自动共享。

需要固定密码时，通过部署环境提供：

nextdoc4j:
  enabled: true
  auth:
    enabled: true
    password: ${NEXTDOC4J_DOC_PASSWORD}

当前登录会话最大空闲时间为 30 分钟。频繁回到登录页时，检查浏览器是否携带会话 Cookie、Cookie 域名与路径、代理转发，以及多实例会话共享方式。

修改密码并重启后，先访问 /doc.html?action=logout 退出旧会话再验证；自定义入口时替换相应路径。非空密码前后的空格参与比较，输入时需要保持一致。

继续阅读：简单认证配置。

文档登录保护的是文档访问；业务接口仍按宿主的 Token、API Key、Session 和权限策略校验。

1. 在接口详情中确认认证方案和角色 / 权限要求。
2. 到“文档管理 → 全局认证”选择对应方案，填写并保存业务凭据。
3. 返回调试查看“实际请求”，确认认证值出现在正确的 Header、Query 或 Cookie 中，同名公共参数、单次覆盖没有带入旧值或禁用该项。
4. 网关中确认当前服务的凭据范围；服务 A 保存的 Token 不应被假定已自动配置给服务 B。

401 通常先排查身份凭据，403 通常先排查权限；最终以宿主后端的响应约定为准。认证方案需要在 components.securitySchemes 中声明，并由接口或根级 security 引用，才能据此注入。

继续阅读：认证、权限与公共参数 · 认证展示插件。

先查看浏览器控制台和 Network 的实际目标。 cURL 不执行浏览器的 CORS 校验，不能据此判断浏览器跨域一定可用。

nextdoc4j.cors=true 可为当前宿主装配内置 CORS 过滤器，但不会修改其他服务或代理的配置；宿主已有对应 CORS Filter 时，也不会重复装配。需要限制来源时，应使用宿主自己的策略。

继续阅读：跨域配置 · 请求设置。

先对照接口声明检查参数位置、Body 格式与“实际请求”。切换编辑模式不会修改后端允许的媒体类型。

详情页中的示例是文档给出的初始值；业务唯一键、权限条件和数据是否存在，仍需要按当前环境填写。

继续阅读：在线请求调试。

按“下游 → 网关转发 → 聚合列表”的顺序检查。以下以网关对外前缀 /user 为例：

确认网关使用 nextdoc4j-gateway-spring-boot-starter、匹配 Web 栈的 Gateway / SpringDoc UI，并设置 nextdoc4j.enabled=true；没有 nextdoc4j.gateway.enabled 这个开关。

自动发现还会检查路由规则：需要 Path 谓词，include-patterns / exclude-routes 匹配的是 routeId；默认过滤器会排除特定的自动发现路由。WebMVC 使用纯 Java RouterFunction 等自定义路由来源时，需要核对路由定位器是否能够读取。

手动配置 gateway.services 只添加文档条目，不会替你创建真实转发路由。

继续阅读：网关聚合插件。

分别核对 OpenAPI URL、servers、业务 Path 和最终调试 URL。能读取文档不代表业务转发规则一定正确。

例如，下游设置 context-path=/order，网关 Path 为 /orders/** 且 StripPrefix=1：

浏览器请求  /orders/order/v3/api-docs
网关转发    /order/v3/api-docs

1. 在“实际请求”中复制最终业务 URL，检查前缀是否漏加或重复。
2. 对照路由的 Path、StripPrefix、下游上下文和 OpenAPI servers，逐段确认。
3. 使用 RewritePath、SetPath 或额外反向代理前缀时，核对实际改写结果；不能直接套用所有 StripPrefix 场景的推导。

注意区分三个配置：nextdoc4j.doc-path 是工作台入口，springdoc.api-docs.path 是服务的 OpenAPI 地址，nextdoc4j.gateway.doc-path 是聚合使用的下游文档后缀。

继续阅读：上下文路径与前缀改写 · 调试地址核对。

服务选择与 SpringDoc 分组是两个层次：先切换到目标服务，再查看其分组。需要读取下游的 swagger-config 时，开启：

nextdoc4j:
  enabled: true
  gateway:
    service-swagger-config-enabled: true

该项默认是 false。开启前，确认通过网关访问下游 /v3/api-docs/swagger-config 能取得分组配置，而且其中的文档 URL 可达。下游仅提供 OpenAPI、没有 swagger-config 接口时，应保持关闭。

继续阅读：多分组与 API-only 下游。

先确定旧的是文档定义还是自己填写过的调试草稿，避免直接清空所有站点数据。

清理调试草稿不会替代后端重新生成 OpenAPI，也不会清除全部认证凭据。网关场景中先确认清理范围是“当前服务”还是“全部服务”。

继续阅读：偏好与本地数据 · 网关刷新与数据检查。