Swagger/Knife4j文档注解不更新问题的常见解决方案

在日常开发中，很多同学都会遇到这样的问题：

明明改了 DTO 的 @Schema、@ApiModelProperty 注解，但打开 doc.html 或 swagger-ui 时，文档就是不更新！

尤其是当 请求/响应对象用到了内部类（nested static class） 时，这个问题更常见。本文就把常见原因和解决方案总结出来，帮大家彻底避坑。

1、问题原因

内部类（Nested Static Class）的缓存机制

• Swagger/Knife4j 对内部类会生成类似 OuterClass$InnerClass 的 schema 名称。
• 这部分有缓存机制，注解改了但类文件没被替换时，Swagger 仍然会使用旧的缓存。

Springdoc/Knife4j 的缓存

• 为了性能，Springdoc/Knife4j 默认会缓存模型（Schema）信息。
• 这就导致改了注解，重启服务后文档有时也不更新。

编译产物未刷新

• IDE（如 IDEA）在二次启动时可能不会重新编译内部类，导致 OuterClass$InnerClass.class 没有更新，Swagger 读到的还是旧字节码。

2、解决方案

方案一：拆分内部类

把内部类单独抽出来，定义为独立的 DTO 类。

@Data
@Schema(description = "采购入库保存请求")
public class ErpPurchaseInSaveReqVO {

    @Schema(description = "保存项列表")
    private List<ErpPurchaseInSaveItemReqVO> items;
}

@Data
@Schema(description = "采购入库保存项")
public class ErpPurchaseInSaveItemReqVO {
    @Schema(description = "商品ID", requiredMode = Schema.RequiredMode.REQUIRED)
    private Long productId;
}

这是最推荐的方式，Swagger/Knife4j 的解析最稳定。

方案二：保留内部类，但加上唯一的 @Schema(name)

如果确实想用内部类，可以这样：

@Data
@Schema(description = "采购入库保存请求")
public class ErpPurchaseInSaveReqVO {

    @Data
    @Schema(name = "ErpPurchaseInSaveItemReqVO", description = "采购入库保存项")
    public static class Item {
        @Schema(description = "商品ID", requiredMode = Schema.RequiredMode.REQUIRED)
        private Long productId;
    }
}

注意：

• name 必须唯一，否则多个内部类会冲突。
• 配合 clean 编译 效果更佳。

方案三：禁用 Springdoc 缓存

在 application-dev.yml 里加上：

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui
  default-flat-param-object: true
  cache:
    disabled: true # 禁用缓存，每次启动重新生成文档

这样每次启动服务时，都会强制重新扫描类并生成文档。

推荐在 开发环境 打开，生产环境保持默认缓存以节省性能。

方案四：确保编译产物更新

• 每次改注解后执行 mvn clean compile，保证 .class 文件更新。
• 或在 IDEA 中执行 Build → Rebuild Project。
• 访问 doc.html 时，使用 Ctrl+F5 强制刷新浏览器缓存。

3、总结推荐

• 开发阶段：建议用 方案二 + 方案三（内部类加 @Schema(name) + 禁用缓存），这样改注解后重启服务就能生效。
• 长期维护：推荐 方案一，把内部类抽成独立 DTO 类，Swagger/Knife4j 解析最稳定，后续协作成本更低。

一句话总结

Swagger/Knife4j 文档不更新，大多数情况下是 内部类缓存 + 文档缓存 + 编译不刷新 三者叠加的锅。
禁用缓存 + 唯一命名 + clean 编译，基本能解决 90% 的问题。

到此这篇关于Swagger/Knife4j文档注解不更新问题的常见解决方案的文章就介绍到这了,更多相关Swagger/Knife4j文档注解不更新内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！