2020 年项目使用 Rap2 维护接口文档时，我尝试了 JApiDocs 1.3，希望减少重复编辑文档和控制器注解的工作。它从 Java 源码、类型和注释提取信息，但这也带来了源码可见范围的限制。

当时使用的依赖与配置

历史依赖为：

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.3</version>
</dependency>

这只是还原当时试用版本，不是当前依赖推荐。对应配置形式：

DocsConfig config = new DocsConfig();
config.setProjectPath("/path/to/project/src");
config.setProjectName("Example API");
config.setApiVersion("V1.0");
config.setDocsPath("/path/to/generated-api-docs");
config.setAutoGenerate(Boolean.TRUE);
Docs.buildHtmlDocs(config);

Docs 与 DocsConfig 来自 io.github.yedaxia.apidocs；路径需换成实际源码和专用输出目录。生成过程会写文件，不要指向需要保留的普通文档目录。实际 API 与目录处理仍应按安装版本核对。JApiDocs 项目说明

这类生成任务更适合受控开发或构建流程，不必每次生产应用启动都生成一遍。

根目录没有结果，src 才找到接口

当时将 projectPath 指向工程根目录，生成接口内容为空；改成该工程的 src 后解析成功。这说明必须检查工具真正扫描到了哪些源码，不能假定它自动理解所有 Maven 模块与构建布局。

这是一份特定工程的观察，不是断言所有版本都必须以 src 结尾。

外部 JAR 与 Object 暴露了边界

当前源码树中的 POJO 能够展开字段，但 common 模块以 JAR 提供的模型没有正常解析；返回 Object 也缺少具体结构信息，String 则能生成相应描述。

源代码解析需要能看到模型定义与注释，单凭编译后的类并不能恢复原来的注释。因此，无注解不意味着无需维护类型和注释，也不保证自动覆盖多模块、泛型包装和统一响应体。

生成后仍要与真实接口对照

先选择一个普通 POJO、一个跨模块 DTO 和一个集合或包装响应，比较生成结果与真实请求/响应。缺字段或类型时，先检查扫描范围和工具能力，不要为适配文档工具就把真实接口改成不准确的 String。

这次试用的结论是：减少注解有价值，但应先验证项目常见类型能否正确表达。它不是对当前版本能力或其他文档方案的统一评价。