SwaggerModelDoc插件仅兼容IDEA 2016–2020.3，2021.1+版本需换用Bitkylin Universal Generate；安装需校验jar包SHA256、路径无中文空格、手动点OK确认；Alt+Insert生效需光标在类内字段行且含标准Javadoc。
SwaggerModelDoc 插件安装失败常见原因
插件无法加载，多数是因为 IDEA 版本不兼容或 jar 包损坏。官方 SwaggerModelDoc.jar 最后更新于 2016 年，仅支持 IDEA 2016–2020.3 版本；2021.1 及之后版本会直接报 Plugin 'SwaggerModelDoc' is incompatible with this installation 错误。
- 确认 IDEA 版本：Help → About → 查看 Build 号，202.x 系列可尝试，211+ 系列必须换插件
- 下载的
SwaggerModelDoc.jar文件需校验 SHA256，部分镜像站提供的是空包或篡改版 - 安装路径不能含中文或空格，
Settings → Plugins → Install plugin from disk选中后务必点击右下角OK而非回车，否则静默失败 - 重启 IDEA 后，在
Settings → Plugins中搜索SwaggerModelDoc，状态栏显示Enabled才算成功
Alt+Insert 插入注解但无反应怎么办
快捷键失效通常不是插件没装好，而是光标位置或类结构不符合触发条件。
- 光标必须落在类内部、字段声明行（如
private String userId;这一行），不能在注释块、方法体或类外空白处 - 类必须有 Javadoc 注释（
/** ... */），且字段级注释也得是标准 Javadoc 格式，//行注释不识别 - 字段不能是
static或final，插件只处理普通实例属性 - 若使用 Lombok 的
@Data，需确保插件在 Lombok 插件之后加载（Settings → Plugins → 拖动排序），否则生成的 getter/setter 会被覆盖
生成的 @ApiModel 和 @ApiModelProperty 注解内容不准
插件直接提取 Javadoc 的第一句作为 @ApiModel.description 和 @ApiModelProperty.value，但实际语义常被截断或错位。
- 类级 Javadoc 若含多行，只取首行；建议把核心描述写在第一行，其余说明放后面
- 字段注释若以
@param开头（如/** @param userId 用户ID */），插件会把@param userId当作 value，结果变成@ApiModelProperty(value = "@param userId") - 嵌套类（如内部
Address）不会自动递归处理，需手动进入该类再执行一次 Alt+Insert - 生成后务必检查
@ApiModel的description是否包含特殊字符（如括号、引号），IDEA 有时会因转义失败导致编译报错
替代方案：Bitkylin Universal Generate 更可靠
原生 SwaggerModelDoc 已停更多年，对现代项目（Spring Boot 3、Java 17+、Lombok 1.18.30+）兼容性差。推荐用 Bitkylin Universal Generate 替代，它支持 Swagger 3（io.swagger.core.v3）和 SpringDoc（org.springdoc）注解。
- Marketplace 搜索
Bitkylin Universal Generate，安装后在Settings → Tools → Bitkylin Universal Generate切换语言为中文 - 右键类 →
Generate Swagger Annotations，可选生成@Schema（SpringDoc）或@ApiModel（Swagger 2），避免版本混乱 - 支持批量处理：选中多个类 → 右键 → 同步生成，比单个类 Alt+Insert 效率高得多
- 它会跳过已存在注解的字段，不会覆盖已有
@ApiModelProperty，适合渐进式接入老项目
真正麻烦的不是加注解，而是维护一致性——字段改名、删字段、加新字段后，旧注解极易遗漏。这类插件只解决“第一次”，后续还得靠 CI 阶段加校验（比如用 spotbugs 检查缺失 @Schema），否则文档和代码早晚脱节。
