Jhipster WebFlux网关Swagger无法启用问题排查咨询

Let's tackle your 404 error on /admin/docs and the underlying NoSuchMethodError step by step. Here are the key areas to check:

1. Fix Springfox Dependency Version Conflicts #

The java.lang.NoSuchMethodError is almost certainly a dependency mismatch between Springfox and Spring WebFlux. JHipster 6.10.3 relies on specific Springfox versions compatible with WebFlux, so:

• Use WebFlux-specific Springfox dependencies: In your pom.xml (Maven) or build.gradle (Gradle), make sure you're using springfox-spring-webflux instead of the MVC-focused springfox-spring-web.
• Unify versions via dependency management: Add a dependency management entry to lock Springfox versions and avoid conflicts from other modules:

  <!-- For Maven -->
  <dependencyManagement>
      <dependencies>
          <dependency>
              <groupId>io.springfox</groupId>
              <artifactId>springfox-dependencies</artifactId>
              <version>2.9.2</version> <!-- Matches JHipster 6.10.3's default -->
              <type>pom</type>
              <scope>import</scope>
          </dependency>
      </dependencies>
  </dependencyManagement>
  

• Clean and rebuild: Run mvn clean install (or ./gradlew clean build) to refresh dependencies and eliminate cached conflicting jars.

2. Verify WebFlux-Specific Swagger Configuration #

Spring WebFlux requires a different Swagger annotation than MVC. Double-check your configuration class:

• Replace @EnableSwagger2 with @EnableSwagger2WebFlux (this is the most common mistake for WebFlux projects):

  @Configuration
  @EnableSwagger2WebFlux
  public class SwaggerConfiguration {
      @Bean
      public Docket api() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.your.gateway.package"))
                  .paths(PathSelectors.any())
                  .build();
      }
  }
  

• Check if the configuration is restricted by a profile (e.g., @Profile("dev")). If so, ensure you're running the gateway in the correct profile where Swagger is enabled.

3. Configure Swagger UI Static Resources for WebFlux #

WebFlux handles static resources differently than MVC, so Swagger UI's assets might not be mapped correctly:

• Add a WebFlux config class to map Swagger's static resources:

  @Configuration
  public class WebFluxStaticConfig implements WebFluxConfigurer {
      @Override
      public void addResourceHandlers(ResourceHandlerRegistry registry) {
          // Map Swagger UI HTML
          registry.addResourceHandler("/swagger-ui.html**")
                  .addResourceLocations("classpath:/META-INF/resources/");
          // Map WebJars (used by Swagger UI)
          registry.addResourceHandler("/webjars/**")
                  .addResourceLocations("classpath:/META-INF/resources/webjars/");
      }
  }
  

4. Validate JHipster Gateway Configuration #

Ensure your JHipster-specific settings are correctly enabling Swagger:

• Check src/main/resources/config/application-dev.yml (or your active profile's config) for:

  jhipster:
    swagger:
      enabled: true
      title: Your Gateway API
      description: API Documentation for Gateway and Microservices
      version: 0.0.1
  

• Confirm the gateway is configured to aggregate microservice Swagger docs. JHipster should generate a GatewaySwaggerResourcesProvider class automatically, but if it's missing, add it to fetch docs from registered services:

  @Component
  public class GatewaySwaggerResourcesProvider implements SwaggerResourcesProvider {
      private final RouteLocator routeLocator;
      private final GatewayProperties gatewayProperties;
  
      public GatewaySwaggerResourcesProvider(RouteLocator routeLocator, GatewayProperties gatewayProperties) {
          this.routeLocator = routeLocator;
          this.gatewayProperties = gatewayProperties;
      }
  
      @Override
      public List<SwaggerResource> get() {
          List<SwaggerResource> resources = new ArrayList<>();
          gatewayProperties.getRoutes().forEach(route -> {
              resources.add(createSwaggerResource(route.getId(), route.getUri().toString() + "/v2/api-docs"));
          });
          return resources;
      }
  
      private SwaggerResource createSwaggerResource(String name, String location) {
          SwaggerResource resource = new SwaggerResource();
          resource.setName(name);
          resource.setLocation(location);
          resource.setSwaggerVersion("2.0");
          return resource;
      }
  }
  

5. Check Security Permissions #

Make sure your security configuration isn't blocking Swagger-related paths:

• In your SecurityConfiguration.java, add these paths to the allowed list (especially for dev profiles):

  .authorizeExchange()
      .pathMatchers("/admin/docs/**", "/swagger-ui.html/**", "/v2/api-docs", "/webjars/**")
      .permitAll()
      // ... other rules
  

6. Verify Microservice Swagger Health #

The gateway's Swagger relies on aggregated docs from your microservices. Test each service individually:

• Access http://your-service-url:port/v2/api-docs directly. If any service returns an error or 404, fix that service's Swagger configuration first (repeat steps 1-3 for each WebFlux service).

Once you address these checks, restart your gateway and try accessing http://localhost:8080/admin/docs again. The NoSuchMethodError should be resolved, and the Swagger UI should load correctly.

内容的提问来源于stack exchange，提问作者Sanjit Vimal