Webflux项目Swagger启动失败，报404静态资源未找到错误

安全阿岳

2026-6-22

WebFlux项目中Swagger无法启动，出现404静态资源错误

我跟着教程开发WebFlux项目，但Swagger启动失败，抛出以下错误：

Whitelabel Error Page
此应用未配置错误视图，因此显示此回退页面。
Thu Jun 20 16:35:41 BRT 2024
[0d766096-1] 发生意外错误（类型=Not Found，状态=404）。
No static resource anime.
org.springframework.web.reactive.resource.NoResourceFoundException: 404 NOT_FOUND "No static resource anime."
at org.springframework.web.reactive.resource.ResourceWebHandler.lambda$handle$1(ResourceWebHandler.java:431)
Suppressed: The stacktrace has been enhanced by Reactor, refer to additional information below:
Assembly trace from producer [reactor.core.publisher.MonoError] :
reactor.core.publisher.Mono.error
org.springframework.web.reactive.resource.ResourceWebHandler.lambda$handle$1(ResourceWebHandler.java:431)

相关代码

AnimeController.java

package mentoria.webflux.spring_web.flux_essentials.controller;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import mentoria.webflux.spring_web.flux_essentials.domain.Anime;
import mentoria.webflux.spring_web.flux_essentials.reposiitory.AnimeRepository;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("animes")
@Slf4j
@RequiredArgsConstructor
public class AnimeController {
    private final AnimeRepository animeRepository;

    @GetMapping
    public Flux<Anime> listAll(){
        return animeRepository.findAll();
    }
}

Anime.java

package mentoria.webflux.spring_web.flux_essentials.domain;

import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.With;
import org.springframework.data.annotation.Id;
import org.springframework.data.relational.core.mapping.Table;

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@With
@Table("anime")
public class Anime {

    @Id
    private Integer id;
    @NotNull
    @NotEmpty(message = "The name of this anime cannot be empty")
    private String name;

}

AnimeRepository.java

package mentoria.webflux.spring_web.flux_essentials.reposiitory;


import mentoria.webflux.spring_web.flux_essentials.domain.Anime;
import org.springframework.data.repository.reactive.ReactiveCrudRepository;

public interface AnimeRepository extends ReactiveCrudRepository<Anime, Integer> {

}

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>mentoria.webflux</groupId>
    <artifactId>spring-web-flux-essentials</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-web-flux-essentials</name>
    <description>Demo project for Spring Boot</description>
    <url/>
    <licenses>
        <license/>
    </licenses>
    <developers>
        <developer/>
    </developers>
    <scm>
        <connection/>
        <developerConnection/>
        <tag/>
        <url/>
    </scm>
    <properties>
        <java.version>17</java.version>
        <blockhound.version>1.0.3.RELEASE</blockhound.version>
        <r2dbc-postgresql.version>0.8.2.RELEASE</r2dbc-postgresql.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.projectreactor.tools</groupId>
            <artifactId>blockhound</artifactId>
            <version>${blockhound.version}</version>
        </dependency>
        <dependency>
            <groupId>io.r2dbc</groupId>
            <artifactId>r2dbc-postgresql</artifactId>
            <version>${r2dbc-postgresql.version}</version>
        </dependency>
        <dependency>
            <groupId>io.projectreactor</groupId>
            <artifactId>reactor-tools</artifactId>
        </dependency>
        <!-- https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-validation -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
            <version>3.3.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-r2dbc</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.projectreactor</groupId>
            <artifactId>reactor-test</artifactId>
            <scope>test</scope>
        </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
        <version>3.3.0</version>
    </dependency>
        <dependency>
            <groupId>javax.validation</groupId>
            <artifactId>validation-api</artifactId>
            <version>2.0.1.Final</version>
        </dependency>
    </dependencies>


    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

我已经检查过导入依赖，但问题仍然无法解决。

问题分析与解决方案

核心问题

你遇到的404错误并非直接来自Swagger，而是请求了不存在的静态资源anime。但根本原因是项目未添加Swagger相关依赖，也未配置WebFlux下的Swagger支持，导致无法访问Swagger界面。另外，pom.xml中同时引入了响应式的spring-boot-starter-data-r2dbc和阻塞式的spring-boot-starter-data-jpa，这会造成上下文冲突，也可能影响Swagger加载。

步骤1：移除冲突依赖

删除pom.xml中的JPA依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
    <version>3.3.0</version>
</dependency>

步骤2：添加Swagger（SpringDoc）依赖

Spring Boot 3.x版本推荐使用SpringDoc OpenAPI支持Swagger，添加以下依赖到pom.xml：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.5.0</version>
</dependency>

步骤3：自定义Swagger配置（可选）

如果需要自定义API文档信息，创建配置类：

package mentoria.webflux.spring_web.flux_essentials.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Anime API")
                        .version("1.0")
                        .description("WebFlux Anime Management API"));
    }
}

步骤4：访问Swagger界面

启动项目后，访问以下地址打开Swagger UI：
http://localhost:8080/swagger-ui.html

额外检查

确认AnimeController的@RequestMapping("animes")路径为复数，避免和静态资源路径冲突
清理Maven缓存，执行mvn clean install重新加载依赖

内容的提问来源于stack exchange，提问作者Isabela Ferreira

Webflux项目Swagger启动失败，报404静态资源未找到错误

相关代码 #

AnimeController.java #

Anime.java #

AnimeRepository.java #

pom.xml #

问题分析与解决方案 #

核心问题 #

步骤1：移除冲突依赖 #

步骤2：添加Swagger（SpringDoc）依赖 #

步骤3：自定义Swagger配置（可选） #

步骤4：访问Swagger界面 #

额外检查 #