SpringdocでClassNotFoundExceptionが発生する問題の解決方法

Springdoc-openapiをバージョン2.6.0から2.7.0にアップグレードした際にClassNotFoundException: org.springframework.web.servlet.resource.LiteWebJarsResourceResolverが発生する問題について解説します。

問題の原因

このエラーはspringdoc-openapiとSpring Bootのバージョン不整合によって発生します。具体的には：

• LiteWebJarsResourceResolverクラスはSpring Framework 6.2で追加されました
• springdoc-openapi 2.7.0では、このクラスの利用を前提としています
• Spring Boot 3.3.xはSpring Framework 6.1.xベースのため、必要なクラスが存在しません

解決策

以下いずれかの方法で対応してください。

方法1: springdoc-openapiをダウングレード（推奨）

Spring Boot 3.3.xを継続利用する場合は、springdoc-openapiを2.6.x系に戻します。

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.6.15</version> <!-- 最新の2.6.xバージョン -->
</dependency>

方法2: Spring Bootをアップグレード

springdoc-openapi 2.7.xを利用する場合は、Spring Bootを3.4.x以上に上げます。

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.4.6</version> <!-- 最新の3.4.xバージョン -->
</parent>

バージョン互換性マトリックス

公式ドキュメントに基づく互換性表：

Spring Framework	Spring Boot	springdoc-openapi
6.1.x	3.3.x	2.6.x
6.2.x	3.4.x～	2.7.x/2.8.x

アップグレード時のベストプラクティス

1. 公式の互換性表で依存関係を確認
2. メジャーバージョンアップは開発環境で先行テスト
3. mvn dependency:treeで依存関係の衝突をチェック

根本原因の技術解説

エラー発生プロセスは以下の通りです：

1. SwaggerConfigがLiteWebJarsResourceResolverを参照
2. Spring Framework 6.1ではクラスが存在しない
3. NoClassDefFoundErrorがスローされる
4. アプリケーションコンテキストのロードに失敗

// 問題の発生ポイント（SwaggerConfig内）
import org.springframework.web.servlet.resource.LiteWebJarsResourceResolver; // 6.2以降のみ

代替案（非推奨）

どうしてもバージョンアップが必要な特殊ケースでは、不足クラスを手動で追加することも理論上可能ですが、非推奨です：

// 互換性レイヤーとして追加（リスク大）
public class LiteWebJarsResourceResolver 
    extends WebJarsResourceResolver {
    // 簡易実装...
}

注意

代替案を採用すると、想定外の動作や将来の不整合リスクが高まります。公式のバージョン互換性を守ることが最良の選択です。

まとめ

springdoc-openapiのバージョン選択では、Spring Bootバージョンとの互換性が最も重要です：

• Spring Boot 3.3.x → springdoc-openapi 2.6.x
• Spring Boot 3.4.x+ → springdoc-openapi 2.7.x/2.8.x

常に公式ドキュメントの互換性表を参照し、安全なアップグレードパスを選択してください。