在日常開發(fā)中，很多同學(xué)都會(huì)遇到這樣的問題：

明明改了 DTO 的 @Schema、@ApiModelProperty 注解，但打開 doc.html 或 swagger-ui 時(shí)，文檔就是不更新！

尤其是當(dāng) 請(qǐng)求/響應(yīng)對(duì)象用到了內(nèi)部類（nested static class） 時(shí)，這個(gè)問題更常見。本文就把常見原因和解決方案總結(jié)出來(lái)，幫大家徹底避坑。

1、問題原因

內(nèi)部類（Nested Static Class）的緩存機(jī)制

• Swagger/Knife4j 對(duì)內(nèi)部類會(huì)生成類似 OuterClass$InnerClass 的 schema 名稱。
• 這部分有緩存機(jī)制，注解改了但類文件沒被替換時(shí)，Swagger 仍然會(huì)使用舊的緩存。

Springdoc/Knife4j 的緩存

• 為了性能，Springdoc/Knife4j 默認(rèn)會(huì)緩存模型（Schema）信息。
• 這就導(dǎo)致改了注解，重啟服務(wù)后文檔有時(shí)也不更新。

編譯產(chǎn)物未刷新

• IDE（如 IDEA）在二次啟動(dòng)時(shí)可能不會(huì)重新編譯內(nèi)部類，導(dǎo)致 OuterClass$InnerClass.class 沒有更新，Swagger 讀到的還是舊字節(jié)碼。

2、解決方案

方案一：拆分內(nèi)部類

把內(nèi)部類單獨(dú)抽出來(lái)，定義為獨(dú)立的 DTO 類。

@Data
@Schema(description = "采購(gòu)入庫(kù)保存請(qǐng)求")
public class ErpPurchaseInSaveReqVO {

    @Schema(description = "保存項(xiàng)列表")
    private List<ErpPurchaseInSaveItemReqVO> items;
}

@Data
@Schema(description = "采購(gòu)入庫(kù)保存項(xiàng)")
public class ErpPurchaseInSaveItemReqVO {
    @Schema(description = "商品ID", requiredMode = Schema.RequiredMode.REQUIRED)
    private Long productId;
}

這是最推薦的方式，Swagger/Knife4j 的解析最穩(wěn)定。

方案二：保留內(nèi)部類，但加上唯一的 @Schema(name)

如果確實(shí)想用內(nèi)部類，可以這樣：

@Data
@Schema(description = "采購(gòu)入庫(kù)保存請(qǐng)求")
public class ErpPurchaseInSaveReqVO {

    @Data
    @Schema(name = "ErpPurchaseInSaveItemReqVO", description = "采購(gòu)入庫(kù)保存項(xiàng)")
    public static class Item {
        @Schema(description = "商品ID", requiredMode = Schema.RequiredMode.REQUIRED)
        private Long productId;
    }
}

注意：

• name 必須唯一，否則多個(gè)內(nèi)部類會(huì)沖突。
• 配合 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 # 禁用緩存，每次啟動(dòng)重新生成文檔

這樣每次啟動(dòng)服務(wù)時(shí)，都會(huì)強(qiáng)制重新掃描類并生成文檔。

推薦在 開發(fā)環(huán)境 打開，生產(chǎn)環(huán)境保持默認(rèn)緩存以節(jié)省性能。

方案四：確保編譯產(chǎn)物更新

• 每次改注解后執(zhí)行 mvn clean compile，保證 .class 文件更新。
• 或在 IDEA 中執(zhí)行 Build → Rebuild Project。
• 訪問 doc.html 時(shí)，使用 Ctrl+F5 強(qiáng)制刷新瀏覽器緩存。

3、總結(jié)推薦

• 開發(fā)階段：建議用 方案二 + 方案三（內(nèi)部類加 @Schema(name) + 禁用緩存），這樣改注解后重啟服務(wù)就能生效。
• 長(zhǎng)期維護(hù)：推薦 方案一，把內(nèi)部類抽成獨(dú)立 DTO 類，Swagger/Knife4j 解析最穩(wěn)定，后續(xù)協(xié)作成本更低。

一句話總結(jié)

Swagger/Knife4j 文檔不更新，大多數(shù)情況下是 內(nèi)部類緩存 + 文檔緩存 + 編譯不刷新 三者疊加的鍋。
禁用緩存 + 唯一命名 + clean 編譯，基本能解決 90% 的問題。

到此這篇關(guān)于Swagger/Knife4j文檔注解不更新問題的常見解決方案的文章就介紹到這了,更多相關(guān)Swagger/Knife4j文檔注解不更新內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論