@documented的核心价值是让自定义注解在javadoc中可见，需配合标准javadoc注释、正确构建参数及与其他元注解组合使用，方能实现文档化契约与开发体验提升。
@Documented 的核心价值在于让自定义注解真正“可见”——它不改变代码行为，但能让注解的用途、参数和约束清晰呈现在 Javadoc 中，成为 API 使用者第一时间能读到的契约说明。
注解要进文档，光加 @Documented 不够
这个元注解只是“开关”，不是“说明书”。它只告诉 javadoc：“把这个注解渲染出来”，但渲染什么内容，全靠你写的 JavaDoc 注释：
- 注解类必须用 /** */ 块注释包裹，不能是
//或/* */ - 每个 public 属性都要有
@param标签说明用途、默认值（如@param value 接口版本号，默认为 "1.0"） - 类级注释里建议写
@summary概述作用，再用正文补充适用场景与限制
生成文档时容易踩的坑
即使注解带了 @Documented 和完整注释，构建过程出错也会让文档“隐身”：
- 执行 javadoc 命令时没包含注解所在包，例如漏掉
-subpackages com.example.annotation - 中文注释未指定编码，需显式加
-encoding UTF-8 -docencoding UTF-8 - 注解用在 private 方法上，而默认 javadoc 不生成 private 成员文档，得加
-private参数
搭配其他机制才发挥最大效用
@Documented 是文档链的起点，不是终点：
- 和
@Retention(RetentionPolicy.RUNTIME)组合使用最常见：既能在运行时被框架反射读取，又能在文档中被开发者查阅 - IDE（如 IntelliJ）会把带 @Documented 的注解说明直接显示在悬停提示里，提升编码时的即时理解效率
- 可与 Swagger/OpenAPI 集成：当注解语义明确（如
@ApiVersion），文档工具能自动提取并注入接口描述
哪些注解建议强制加 @Documented
面向外部使用者的公共 API 注解，尤其是框架层或中间件层定义的语义化注解：
- 版本控制类：
@ApiVersion、@Since - 权限与安全类：
@RequiresPermission、@RestrictedApi - 序列化/传输控制类：
@JsonIgnoreIf（自定义版）、@MaskField - 业务标记类：
@Idempotent、@AuditLog
内部仅用于编译检查或 AOP 切面的注解，若不对外暴露，可不加。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
