@Documented 使自定义注解及其JavaDoc出现在生成的JavaDoc文档中，提升API可读性；需配合完整注释、正确构建配置及文档可见性设置才生效。
@Documented 是 Java 中一个关键的元注解，它的作用很直接：让自定义注解出现在生成的 JavaDoc 文档中。它本身不改变程序行为，但能显著增强公共 API 的可读性与协作效率——前提是配合规范的注释习惯和合理的文档生成流程。
为什么 @Documented 能提升 API 可读性
当一个注解被 @Documented 标记后，Javadoc 工具在生成 HTML 文档时，会把该注解及其属性说明一并纳入对应类、方法或字段的文档页。使用者无需翻源码，就能看到：
- 这个注解是干什么的（通过 @summary 或注释正文）
- 它支持哪些参数（@param 标签描述）
- 适用场景和约束（如“仅用于 controller 层方法”）
- 是否可重复使用、是否继承等行为特征（由其他元注解体现，@Documented 让这些信息可见）
正确使用 @Documented 的三个前提
它不是“开关式”功能，必须搭配以下实践才真正生效：
-
注解本身需带完整 JavaDoc 注释：用
/** ... */包裹，而非单行//或/* ... */ -
注解属性要有明确说明：每个
public属性都应在注释中用@param name解释用途、默认值、取值范围 -
构建时启用 JavaDoc 输出且包含该注解所在包：例如执行
javadoc -package com.example.annotation，确保注解类被扫描到
典型错误与改进建议
常见误区会削弱 @Documented 的价值：
- 只加 @Documented，但注解类没写任何 JavaDoc —— 文档里只显示注解名，无解释
- 注释写成中文但未配置编码（如未加
-encoding UTF-8 -docencoding UTF-8）—— 出现乱码，可读性归零 - 注解用于 private 方法，而 Javadoc 默认不生成 private 成员文档（需显式加
-private参数）—— 用户根本看不到
建议统一要求所有对外暴露的自定义注解（尤其是框架层、中间件层）必须带 @Documented，并纳入 CI 流程检查：若注解类缺少 JavaDoc，构建失败。
与其他文档手段协同增效
@Documented 是 Java 原生文档链的一环，不是孤立方案：
- 搭配 Swagger/OpenAPI：注解（如 @ApiParam、@ApiResponse）被工具识别后，自动注入接口文档
- 结合 IDE：IntelliJ 或 VS Code 在悬停提示中展示带 @Documented 的注解说明，提升实时可读性
- 服务化文档：将生成的 JavaDoc 部署为静态站点，与 Spring REST Docs 或 NSwag 页面并列，形成统一开发者门户
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
