@documented 是让自定义注解出现在 javadoc 文档中的标记，需配合规范注释、正确构建配置及 utf-8 编码三者缺一不可，与 swagger/springdoc 互补而非冲突。
@Documented 不是让文档“自动生成”的开关，而是让自定义注解本身出现在 Javadoc 文档里的关键标记。它不生成接口描述、不提取参数结构，只决定“这个注解要不要被看见”。真正起作用的前提，是它和规范注释、构建配置一起配合。
自定义注解必须带 @Documented 才能进文档
加了 @Documented，Javadoc 工具在扫描类、方法或字段时，会把该注解名及其 JavaDoc 说明一并渲染到 HTML 页面对应位置；没加，哪怕你写了 @ApiVersion("2.1")，文档里也完全不会出现这行标注。
- 它只能用在其他注解上（
@Target(ElementType.ANNOTATION_TYPE)） - 它本身不影响运行逻辑，也不改变编译行为
- 常见搭配是
@Retention(RetentionPolicy.RUNTIME)，方便框架反射读取
光加 @Documented 没用：三件事缺一不可
很多团队加了 @Documented 却发现文档里还是空的，问题往往出在这三个环节：
Java JDK 25
下载
Java JDK 25 来自 OpenJDK 官方归档，版本为 JDK 25，本条下载地址已指向官方 Windows x64 zip 安装包直链，适合调试旧项目或兼容旧版 Java 运行环境。
- 注解类本身没写 JavaDoc：必须用
/** */包裹，不能是//或/* */ - 注解属性没说明：每个 public 属性都要用
@param标明用途、默认值、是否必填 - 构建时没扫到注解包：Maven 需确保
javadoc插件包含注解所在 package，例如-subpackages com.example.annotation
中文注释要配编码参数，否则全是乱码
IDEA 或命令行生成 Javadoc 时，如果注释用了中文但没指定字符集，浏览器打开就是方块或问号。必须显式加上：
-
-encoding UTF-8（源文件编码） -
-docencoding UTF-8（生成 HTML 的编码） -
-charset UTF-8（HTML meta 中声明的 charset）
在 IDEA 的 Generate JavaDoc 对话框里，“Other command line arguments”栏填这三项，是最稳妥的做法。
和 Swagger/SpringDoc 不冲突，反而互补
@Documented 解决的是“注解本身的说明”，而 Swagger 解决的是“HTTP 接口怎么调”。两者可以共存：
- 你写一个
@ValidatedParam注解并标上 @Documented，开发者看 Javadoc 就知道它校验什么规则 - 你在 Controller 方法上用这个注解，SpringDoc 仍能正常识别请求参数，生成 OpenAPI 文档
- IDE 悬停提示也会显示该注解的 JavaDoc，提升编码时的即时可读性
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
