不能直接通过Annotation Processor解析JavaDoc生成OpenAPI文件，因javadoc不参与AST流程、getDocComment()在JDK11+基本失效，且需自行解析标签；应改用Spoon或javadoc-toolkit等编译期外工具。
不能直接通过 Annotation Processor 解析 JavaDoc 生成 OpenAPI 描述文件。
原因很实在：JavaDoc 是编译器在 javac -doc 阶段单独调用 com.sun.tools.javadoc.Main 处理的，它不走标准的 AST 解析流程，也不暴露给 RoundEnvironment 或 Element API。Annotation Processor 能拿到的只有源码 AST 中的 Element（类、方法、字段等），而 JavaDoc 注释虽然附着在 Element 上，但其内容是原始字符串，没有被解析成结构化模型（比如参数名、返回值描述、@param 标签语义）。
为什么 getDocComment() 返回 null 或空字符串
即使你调用 element.getEnclosedElements() 或 element.getAnnotationMirrors()，也拿不到 JavaDoc 内容——除非你在 processor 中显式启用 -Xdoclint:none 并配合 ProcessingEnvironment.getElementUtils().getDocComment(element)，但这个方法在多数 JDK 版本（尤其是 JDK 17+）中默认返回 null，因为 javac 默认不保留 JavaDoc 字符串到编译期处理阶段。
- 这是 javac 的设计限制，不是 bug，也不是配置能绕过的
-
Elements.getDocComment(Element)在 JDK 8 下可能有效，但在 JDK 11 及以后基本失效 - 即便能取到原始字符串，你也得自己实现 JavaDoc 解析器来识别
@param、@return、@throws等标签，这和 OpenAPI Schema 映射逻辑一样重
替代方案：用 Spoon 或 javadoc-toolkit 做预处理
真要从 JavaDoc 生成 OpenAPI，得跳出 Annotation Processor 范式，改用能在编译前或编译后独立分析源码的工具：
-
Spoon：静态代码分析框架，可完整解析 Java 源码 + JavaDoc 注释，并提供CtMethod.getDocComment()等可靠 API，适合写 CLI 工具在compileJava任务后执行 -
javadoc-toolkit（如io.github.robwin:javadoc-toolkit）：专为提取 JavaDoc 结构设计，支持将@param name description映射为 OpenAPI Parameter 对象 - Gradle 插件
org.springdoc.openapi-gradle-plugin实际也是在编译后扫描 classpath + 反射 + 注解，而非依赖 JavaDoc 字符串
如果你坚持用 APT，唯一可行路径是：要求开发者把关键 OpenAPI 信息写进自定义注解（如 @ApiParam(description = "用户邮箱")），再由 processor 提取——但这已经不是“解析 JavaDoc”，而是放弃 JavaDoc，改用注解驱动。
build.gradle 中容易漏掉的关键配置
即使你用 Spoon 写了个生成器，也得注意构建时序问题：
- 必须在
compileJava之后、processResources之前运行，否则源码路径不可见 - 不能放在
annotationProcessor配置块里，否则会被当作 APT 依赖加载，导致 ClassLoader 冲突 - 推荐方式：
task generateOpenapiFromJavadoc(type: JavaExec) { classpath = sourceSets.main.output + sourceSets.main.runtimeClasspath }
真正难的不是生成 JSON，而是让 JavaDoc 描述和实际签名对齐——比如 @param userId 写了，但方法签名里根本没有叫 userId 的参数，这种错漏 APT 根本发现不了，只能靠额外校验步骤兜底。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
