L'apparition d'une page "Whitelabel Error Page" lors de la tentaitve d'accès à l'interface Swagger dans une application Spring Boot est un problème fréquent. Voici les étapes techniques pour diagnnostiquer et corriger les causes courantes de ce dysfonctionnement.

1. Configuration des dépendances Maven

Assurez-vous que votre fichier pom.xml inclut les bibliothèques nécessaires. Une version incohérente entre le cœur de Swagger et l'interface utilisateur peut provoquer des erreurs de chargement.

<properties>
    <swagger.version>2.9.2</swagger.version>
</properties>

<dependencies>
    <!-- Bibliothèque principale Springfox -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <!-- Interface graphique Swagger UI -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>
</dependencies>

2. Initialisation de la configuration Swagger

La classe de configuration doit être annotée correctement pour activer la génération automatique de la doucmentation. Il est recommandé d'utiliser des profils pour limiter l'exposition de Swagger aux environnements de développement ou de test.

@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class RestApiDocConfig {

    @Value("${server.servlet.context-path:/}")
    private String rootPath;

    @Bean
    public Docket documentationRegistry() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Internal-API")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.entreprise.projet.web"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(generateMetaData());
    }

    private ApiInfo generateMetaData() {
        return new ApiInfoBuilder()
                .title("Documentation Service API")
                .description("Spécifications techniques du module : " + rootPath)
                .contact(new Contact("Support Tech", "https://site-web.com", "dev@example.com"))
                .version("1.0.1")
                .build();
    }
}

3. Exposition des ressources statiques

Si vous utilisez une configuration personnalisée de WebMvc, Spring Boot peut cesser de mapper automatiquement les ressources statiques de Swagger. Vous devez alors les déclarer manuellement dans une classe implémentant WebMvcConfigurer.

@Configuration
public class WebMvcAssetConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

4. Vérification de l'URL et du Context-Path

Une erreur fréquente provient d'une URL mal formée, notamment lorsque l'application définit un chemin racine spécifique via la propriété server.servlet.context-path.

• Sans context-path : L'accès se fait généralement via http://localhost:8080/swagger-ui.html.
• Avec context-path (ex: /api/v1) : L'adresse correcte devient http://localhost:8080/api/v1/swagger-ui.html.

Si l'erreur persiste malgré ces configurations, vérifiez que vos filtres de sécurité (Spring Security) n'interceptent pas les requêtes vers les endpoints /v2/api-docs et /swagger-ui.html.