Java API文档生成实战：自定义注解的@Documented应用-java教程-PHP中文网

@documented的作用是让自定义注解出现在javadoc生成的api文档中，仅控制注解自身是否被列出，需置于@interface定义上方并配合文档注释使用，否则文档中不会显示该注解。

java api文档生成实战：自定义注解的@documented应用

@Documented的作用很明确：让自定义注解出现在Javadoc生成的API文档里。它不处理普通注释，也不自动补全方法说明或参数描述，只决定“这个注解本身是否被列出来”。用对了，别人看文档时一眼就能看到你加的@ApiVersion、@DeprecatedSince这类标记；用错了，文档里就完全看不到它的存在。

什么时候必须加@Documented？

当你希望使用者在阅读Javadoc HTML页面时，能直观看到某个类、方法或字段上应用了你的自定义注解，就必须加上它。比如：

标注接口兼容性的@ApiVersion
标记配置项来源的@ConfigSource
说明权限要求的@RequireRole

这些注解本身承载语义，不是内部工具用的调试标记。如果没加@Documented，即使代码里写了@ApiVersion(3)，生成的文档里也不会出现这行信息。

怎么写才真正生效？

关键不在用法，而在位置和配合：

Java JDK 25

Java JDK 25 来自 OpenJDK 官方归档，版本为 JDK 25，本条下载地址已指向官方 Windows x64 zip 安装包直链，适合调试旧项目或兼容旧版 Java 运行环境。

下载

必须直接写在@interface定义上方，不能放在使用处
通常搭配@Retention(RetentionPolicy.RUNTIME)，但两者职责不同：一个管运行时反射读取，一个管文档展示
要在注解定义前加标准文档注释（/** ... */），这样Javadoc才会显示注解本身的用途说明

例如：

/**
 * 标明当前方法支持的最低API版本号
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
    int value() default 1;
}

验证它有没有起作用

最可靠的方式是实际生成一次文档：

用命令行：javadoc -d docs UserService.java
或在IDEA中：Tools → Generate JavaDoc → 选好输出路径和范围
打开生成的HTML，在类/方法详情页顶部找“Annotations:”那一栏

有@ApiVersion(2)就说明@Documented生效；去掉它再试一次，这行会消失。

常见误区提醒

很多人以为加了@Documented就能让参数说明、返回值描述自动进文档——其实不是：

@Documented不管/** */里的内容，那些仍需手动写@param、@return
它也不影响IDE里的悬浮提示，那是编辑器自己解析的，和Javadoc无关
普通单行//或多行/* */注释永远不会被Javadoc提取，只有文档注释才行

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！