Cannot access swagger-ui.html (401) の解決方法【2025年最新版】
エラーの概要・症状
エラーメッセージ「Cannot access swagger-ui.html (401)」は、Spring Boot アプリケーションにおいて、Swagger UI へのアクセスが拒否されたことを示します。このエラーは、認証が必要なエンドポイントに対して、適切な認証情報なしでアクセスしようとした場合に発生します。具体的には、HTTP ステータスコード 401 は「Unauthorized」を意味しており、リクエストが適切な認証情報を持っていないことを示しています。
このエラーが発生すると、開発者やユーザーは Swagger UI にアクセスできず、API ドキュメンテーションやテストが行えなくなります。特に、API の開発やデバッグを行う際には非常に困る問題です。また、ユーザーは「401 Unauthorized」と表示され、どのように対処すればよいのかわからずに困惑することが多いです。
このエラーが発生する原因
「Cannot access swagger-ui.html (401)」が発生する原因は、主に以下のようなものが考えられます。
1. 認証設定の不備
Swagger UI へのアクセスが認証されていない場合、HTTP ステータス 401 が返されます。これは、API エンドポイントに対するセキュリティ設定が原因です。Spring Security を使用している場合、正しい認証情報を提供しない限り、Swagger UI にアクセスできません。
2. JWT トークンの不正
もし JWT（JSON Web Token）を使用している場合、トークンが無効であったり、期限切れの場合もこのエラーが発生します。トークンが正しくない場合、サーバーはリクエストを認可しません。
3. Web セキュリティ設定の誤り
Spring Security の設定に誤りがある場合も、このエラーが発生します。特に、Swagger UI へのアクセスを許可する設定がされていないと、401 エラーが表示されます。
4. CORS 設定の不備
もしリクエストが異なるオリジンから行われている場合、CORS（Cross-Origin Resource Sharing）設定が不適切だと、401 エラーが発生することがあります。これは、ブラウザが異なるオリジンからのリクエストを制限するためです。
解決方法1（最も効果的）
このエラーを解決するための最も効果的な方法は、Spring Security の設定を見直し、Swagger UI へのアクセスを許可することです。以下の手順を実行してください。
H3: 手順1-1（具体的なステップ）
pom.xmlファイルに必要な依存関係を追加します。Swagger と Spring Security を使用するため、以下の依存関係を追加してください。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>com.auth0</groupId>
<artifactId>java-jwt</artifactId>
<version>3.8.3</version>
</dependency>H3: 手順1-2（詳細な操作方法）
- セキュリティ設定を行うためのクラスを作成します。以下のように
OAuth2SecurityConfigクラスを作成してください。
@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
@EnableWebSecurity
public class OAuth2SecurityConfig extends WebSecurityConfigurerAdapter {
private String publicKey = "...";
@Override
protected void configure(HttpSecurity http) throws Exception {
http
.cors().and()
.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
.and()
.exceptionHandling().authenticationEntryPoint((req, rsp, e) -> rsp.sendError(HttpServletResponse.SC_UNAUTHORIZED));
http
.authorizeRequests()
.antMatchers(
"/*/v2/api-docs",
"/v2/api-docs",
"/swagger-ui.html",
"/swagger-ui.html/**",
"/webjars/springfox-swagger-ui/**",
"/swagger-resources/**",
"/actuator/*"
).permitAll()
.anyRequest().authenticated()
.and()
.addFilterBefore(new JwtFilter(publicKey), UsernamePasswordAuthenticationFilter.class);
}
}- 上記の設定を追加した後、Swagger UI へのアクセスを再試行してください。
H3: 注意点とトラブルシューティング
- もしトークンを使用している場合は、トークンが正しいことを確認してください。
- Swagger UI へのアクセスが許可されているか、CORS 設定も確認してください。
- 変更後は、アプリケーションを再起動することを忘れないでください。
解決方法2（代替手段）
もし上記の方法で解決しない場合、次の手段を試みることができます。
- Swagger UI の静的リソースへのアクセスを確認します。
application.propertiesに以下の設定を追加してください。
spring.web.resources.add-mappings=true- Spring Security の設定において、Swagger UI へのアクセスを許可するパスを確認し、必要に応じて追加してください。
-
これでも解決しない場合、Swagger のバージョンを確認し、最新のバージョンにアップデートすることも検討してください。
解決方法3（上級者向け）
上級者向けのアプローチとして、JWT トークンの検証をカスタマイズする方法があります。以下の手順でカスタムフィルターを作成します。
- 新しいクラス
JwtFilterを作成し、トークンの検証を行います。
public class JwtFilter extends GenericFilterBean {
private JWTVerifier verifier;
public JwtFilter(String key) throws Exception {
// トークンの検証に使用する公開鍵を設定
this.verifier = JWT.require(Algorithm.RSA512(publicKey, null)).build();
}
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain) throws IOException, ServletException {
// トークンを検証し、認証情報を設定
filterChain.doFilter(request, response);
}
}OAuth2SecurityConfigクラスでこのフィルターを使用するように設定します。
エラーの予防方法
エラーを未然に防ぐためには、以下の予防策を講じることが重要です。
- **定期的なセキュリティ設定の見直し**: Spring Security の設定を定期的に見直し、変更が必要な場合は適宜修正します。
- **トークンの管理**: JWT トークンの有効期限を管理し、期限切れのトークンを使用しないようにします。
- **API ドキュメンテーションの更新**: Swagger UI の設定やエンドポイントのドキュメンテーションを最新の状態に保つことで、開発者が正しい情報に基づいて作業できるようにします。
関連するエラーと対処法
類似のエラーとして、以下のようなものがあります。
- **Cannot access /api/v1/resource (403)**: アクセス権限がない場合に発生。ユーザー権限の設定を見直す必要があります。
- **Cannot access /swagger-ui/**: Swagger UI へのアクセスが許可されていない設定が原因。セキュリティ設定を修正することで対処可能です。
まとめ
エラー「Cannot access swagger-ui.html (401)」は、主に認証情報の不備やセキュリティ設定の誤りに起因します。上記の手順に従って設定を見直すことで、問題を解決できるでしょう。また、定期的なメンテナンスやトークンの管理を行うことで、今後のエラーを未然に防ぐことができます。次のステップとして、環境設定を見直し、Swagger UI へのアクセスが正常に行えるかを確認してください。
コメント