NextDoc4j

主题

常见问题 FAQ ​

这里汇总了社区用户在接入 NextDoc4j 时最常遇到的环境兼容性、参数展示异常与构建配置问题。请先对照排查。

💡 快速定位

如果以下常见问题未能解决您的疑问，欢迎加入 官方微信讨论群 或在 GitHub Issues 发起提问。

Boot 3.4.0+ 基线要求default-flat-param-object-parameters 编译参数

核心排错指南速查 ​

错误现象： 应用启动时出现 java.lang.ClassNotFoundException: org.springframework.web.servlet.resource.LiteWebJarsResourceResolver 导致上下文启动失败。
根本原因： LiteWebJarsResourceResolver 是 Spring Boot 3.4.0 引入的新类。当前工程的 Spring Boot 版本低于 3.4.0（例如仍在 3.2.x 或 3.3.x）。

版本兼容性矩阵（硬性要求）：

核心组件最低支持版本推荐版本说明
Spring Boot3.4.03.5.x / 4.x硬性基线，低于 3.4.0 无法加载资源解析器
SpringDoc2.8.0 (Boot 3) / 3.0.0 (Boot 4)2.8.17 (Boot 3) / 3.0.3 (Boot 4)1.4.0 起由宿主工程自行引入 starter
JDK1721+ (LTS)全面适配现代 Java 虚拟机
💡 解决方案： 请将宿主工程的 spring-boot-starter-parent 版本升级至 3.4.0 及以上（推荐 3.5.x）。
错误现象： 接口方法入参为 UserDTO，但文档中仅显示类型名称，内部字段（如 name, age）未展开。
原因剖析： SpringDoc 默认不会自动平铺展开自定义入参对象的成员属性，需要开启平铺参数解析。

解决方案（推荐方式一 全局配置）：

application.yml
springdoc:
  # 将对象内的入参属性自动平铺展示（推荐）
  default-flat-param-object: true
错误现象： 接口的 @RequestParam 或 @PathVariable 形参名称在文档中变成 arg0, arg1 或偶尔丢失。
原因剖析： Java 编译器默认编译出的 .class 字节码中不保留真实的方法参数名。SpringDoc 无法通过反射精准推断入参名称。

解决方案：在 Maven 编译插件中启用 -parameters

pom.xml (maven-compiler-plugin)
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <encoding>${project.build.sourceEncoding}</encoding>
        <!-- 保留方法参数名以确保 SpringDoc 入参正常展示 -->
        <compilerArgument>-parameters</compilerArgument>
    </configuration>
</plugin>

最后更新于: