idea中没有名为“doc”的插件，实际可用的是doc view（id 15305，支持文档生成与编辑回写）和easy javadoc（专注javadoc自动生成）；需在plugins中搜“doc view”确认安装，右键方法出现doc editor或generate doc且左侧有文档图标即成功。
IDEA里叫“Doc”的插件并不存在——你大概率是把 Doc View 或 Easy Javadoc 记混了，也可能是看到别人口误说成“Doc”。真正能用、活跃维护、功能完整的只有 Doc View（支持接口文档生成+编辑回写）和 Easy Javadoc（专注自动生成标准 JavaDoc 注释）。选错插件，配置半天也跑不起来。
怎么确认自己装的是 Doc View 而不是“Doc”？
在 IDEA 的 Settings → Plugins 里搜索 Doc View，而不是“Doc”。它的官方 ID 是 15305，作者是 liuzhihang，GitHub 地址是 https://github.com/liuzhihang/doc-view。如果搜出来名字带“Doc”但没作者、没 GitHub、评分低于 4.0，基本是过期或废弃插件，别装。
- 装完后，右键任意 Controller 方法，菜单里出现
Doc Editor或Generate Doc才算成功 - 左侧工具栏出现
Doc View图标（一个文档图标），点开会显示接口树状列表 - 不支持 Java 17 以下版本；如果你用的是 Java 8，
Doc View2.x 会直接报NoClassDefFoundError: java.net.http.HttpClient
Doc View 生成的 Markdown 文档字段从哪来？
它不读 @Api 或 @ApiOperation，也不依赖 Swagger 注解。默认只认三类来源：
- 方法上的 JavaDoc 注释：描述取
/** ... */的首行文本；@param和@return会被解析为请求/返回字段 - 实体类字段的 JavaDoc：每个
private String name;上的注释，会变成请求参数说明；如果加了@required，就标记为必填 - Spring MVC 的
@PathVariable、@RequestParam、@RequestBody注解：自动识别参数位置和是否必填，但不会读取注解里的value或defaultValue
注意：@docName 这种自定义 tag 必须写在 JavaDoc 里，比如 /** @docName "用户登录接口" */，否则接口名还是取方法名。
为什么 Doc View 编辑后不回写到源码？
这是最常被卡住的点：点击 Doc Editor 里的“确定”，但 Java 文件里的注释没变。根本原因是文件未保存或权限受限。
- 确保你要编辑的方法/字段所在的 Java 文件是已打开且**未只读**状态（右下角不显示
Read-only） - 编辑完必须点
OK，不是按回车；点Cancel或关窗口都不会写入 - 如果项目用了 Lombok，且字段上有
@Getter/@Setter，Doc View仍会尝试往字段上写注释——但它写的是 Lombok 生成字段的注释位置，IDEA 可能不渲染，实际生效需手动移到private字段声明上方 - 修改后没立刻看到效果？重启 IDEA 或执行
File → Reload project from Maven（如果是 Maven 项目）
导出到 YApi / 语雀失败怎么办？
Doc View 的上传功能依赖 HTTP 客户端，Java 17+ 默认禁用旧版 TLS，而部分 YApi 版本（v1.12 之前）或私有部署的语雀网关还在用 TLS 1.1。
- 先检查 IDEA 底部状态栏是否有红色错误提示，内容通常是
javax.net.ssl.SSLHandshakeException - 临时解决：在
Help → Edit Custom VM Options里追加一行-Djdk.tls.client.protocols=TLSv1.2,TLSv1.3，重启 IDEA - 更稳妥的做法：升级 YApi 到 v1.13+，或让运维把语雀反向代理的 TLS 配置调高
- 上传前务必确认
Settings → Other Settings → Doc View → Upload Config里的 URL、Token、Project ID 全部填对——少一个斜杠或大小写错误都会 401
复杂点在于：它把整个接口树当做一个 Markdown 文件上传，不支持单个接口增量更新。一旦上传成功，就得靠人工在 YApi 里做 diff，没法自动覆盖旧版本。
