SpringBoot集成SpringDoc OpenAPI完整步骤（替代SpringFox/Swagger2）

来源：互联网 2026-07-24 08:22:03

SpringBoot集成SpringDocOpenAPI替代SpringFox，2.x与3.x依赖版本不同。引入依赖后通过配置类自定义文档标题，使用@Tag、@Operation等注解标注接口，启动后访问/swagger-ui/index.html。需注意SpringSecurity放行资源及生产环境关闭文档。

前置说明

SpringFox（即旧版 Swagger2）在 SpringBoot 2.6+ 和 3.x 上兼容性较差，容易报错。因此本文直接使用 SpringDoc OpenAPI 3，页面仍保持熟悉的 Swagger UI 风格。
SpringBoot 2.x 和 3.x 的依赖版本不同，下文已分别标注。
全程按步骤操作，复制后即可运行。

最终访问地址：http://localhost:你的端口/swagger-ui/index.html

长期稳定更新的攒劲资源： >>>点此立即查看<<<

第 1 步：引入 Maven 依赖 pom.xml

情况 A：SpringBoot 3.x（JDK17+）



    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.5.0

情况 B：SpringBoot 2.x（JDK8 / JDK11）


    org.springdoc
    springdoc-openapi-ui
    1.7.0

引入后刷新 Maven，等待依赖下载完成即可。

第 2 步：创建 Swagger 配置类（可选，用于修改文档标题、描述）

新建 SwaggerOpenApiConfig.java，放在 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 SwaggerOpenApiConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("项目后端接口文档")     //文档标题
                        .version("V1.0")               //版本
                        .description("所有业务接口在线调试文档")); //描述
    }
}

不写此配置类也能正常打开 Swagger，只是顶部没有自定义标题。

第 3 步【核心】给你的 Controller 接口添加注解（让接口显示在文档）

OpenAPI3 常用注解对照表

注解	作用
`@Tag(name = "模块名称")`	加在 Controller 类上，划分接口模块
`@Operation(summary = "接口名称",description = "详细描述")`	标记单个接口
`@Parameter(description = "参数说明")`	url 传参说明
`@Schema(description = "字段注释")`	实体类、DTO 字段注释

其实不加注解也能使用。SpringDoc 会自动扫描所有 @RestController，直接生成文档。

Controller 完整示例

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
@Tag(name = "用户管理模块")
public class UserController {
    @GetMapping("/get")
    @Operation(summary = "根据ID获取用户信息", description = "传入用户id，查询基础用户数据")
    public String getUser(Long userId){
        return "用户信息";
    }
}

DTO / 实体类示例（返回对象展示注释）

在 Swagger 文档中，当接口返回或接收对象时，字段上的 @Schema 注解能让文档清晰地展示每个字段的含义和示例值。

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "用户返回实体")
public class UserDTO {
    @Schema(description = "用户唯一ID", example = "1001")
    private Long userId;

    @Schema(description = "用户姓名", example = "张三")
    private String userName;

    @Schema(description = "用户邮箱", example = "zhangsan@example.com")
    private String email;

    @Schema(description = "创建时间", example = "2023-10-01 12:00:00")
    private String createTime;
}

关键点：

@Schema(description = "...")：用于描述整个类或单个字段的作用。

@Schema(example = "...")：提供字段的示例值，方便在 Swagger UI 中直接测试。

实体类（如 JPA Entity）的注解用法完全相同，但通常用于数据库映射。

确保导入正确的包：import io.swagger.v3.oas.annotations.media.Schema;，不要使用旧版 Swagger2 的 @ApiModel。

这样配置后，Swagger 文档中该对象的字段将显示清晰的注释和示例，可读性大幅提升。

第 4 步：启动项目，访问文档地址

http://localhost:8080/swagger-ui/index.html

将 8080 替换为你项目的 server.port 端口。

如果打不开页面：往下看【常见问题排查】

成功了

SpringBoot集成SpringDoc OpenAPI完整步骤（替代SpringFox/Swagger2）

第 5 步（可选）：SpringSecurity / 拦截器放行 swagger 资源

如果项目使用 SpringSecurity、自定义拦截器，会拦截 swagger 地址，导致页面无法加载，需要放行以下地址：

/v3/api-docs/**
/swagger-ui/**
/swagger-ui/index.html

SpringSecurity 放行示例

@Override
public void configure(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests()
            .requestMatchers("/v3/api-docs/**","/swagger-ui/**").permitAll()
            .anyRequest().authenticated();
}

自定义 WebMvc 拦截器放行

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(loginInterceptor)
            .addPathPatterns("/**")
            .excludePathPatterns("/v3/api-docs/**","/swagger-ui/**");
}

第 6 步（可选）区分环境：只开发环境开启 Swagger

一般生产环境关闭接口文档，使用 @ConditionalOnProperty 修改配置类：

@Configuration
// yml配置 springdoc.enable=true 才开启
@ConditionalOnProperty(name = "springdoc.enable", havingValue = "true")
public class SwaggerOpenApiConfig {
    // ...代码不变
}

application.yml

springdoc:
  enable: true # dev开启；prod改为false

高频踩坑排查清单（重点）

问题 1：打开页面，但一片空白，看不到自己写的接口

Controller 必须加 @RestController
接口方法必须是 public
启动项目后不要直接访问静态 html，先让 Spring 加载所有 Controller
检查请求路径是否有统一前缀 server.servlet.context-path，访问地址要带上前缀

问题 2：404 找不到页面

核对地址！

正确：/swagger-ui/index.html

旧 swagger2 地址 /swagger-ui.html 在 SpringDoc 中失效

问题 3：实体类返回值不显示注释

确认导入注解包：

import io.swagger.v3.oas.annotations.media.Schema;

不要导错旧 swagger2 的 @ApiModel

问题 4：SpringBoot3 启动报错

必须使用 springdoc-openapi-starter-webmvc-ui，不能使用 2.x 旧依赖

补充：如果你执意使用老版本 Swagger2（SpringFox，不推荐）

pom 依赖


    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

配置类

import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 重点！修改为你的controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .build();
    }
}

访问地址：http://localhost:8080/swagger-ui.html

SpringBoot 2.6 以上必须额外配置 yml 解决路径匹配报错

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

问题 5：本地有 Swagger UI 文件吗

你在项目目录中找不到任何 swagger-ui 的 HTML/CSS/JS 文件。
Swagger UI 的静态文件打包在 JAR 依赖包内部。

SpringBoot集成SpringDoc OpenAPI完整步骤（替代SpringFox/Swagger2）

侠游戏发布此文仅为了传递信息，不代表侠游戏网站认同其观点或证实其描述

热游推荐

更多

DreamStudio

Android/ | AI绘图

2026-06-30

下载
Pixlr

Android/ | AI绘图

2026-06-30

下载
Playground AI

Android/ | AI绘图

2026-06-30

下载
Adobe Firefly

Android/ | AI绘图

2026-06-30

下载
Canva AI

Android/ | AI绘图

2026-06-30

下载
Ideogram

Android/ | AI绘图

2026-06-30

下载
Leonardo AI

Android/ | AI绘图

2026-06-30

下载
Stable Diffusion

Android/ | AI绘图

2026-06-30

下载

SpringBoot集成SpringDoc OpenAPI完整步骤（替代SpringFox/Swagger2）

前置说明

第 1 步：引入 Maven 依赖 pom.xml

情况 A：SpringBoot 3.x（JDK17+）

情况 B：SpringBoot 2.x（JDK8 / JDK11）

第 2 步：创建 Swagger 配置类（可选，用于修改文档标题、描述）

第 3 步【核心】给你的 Controller 接口添加注解（让接口显示在文档）

OpenAPI3 常用注解对照表

Controller 完整示例

DTO / 实体类示例（返回对象展示注释）

第 4 步：启动项目，访问文档地址

第 5 步（可选）：SpringSecurity / 拦截器放行 swagger 资源

SpringSecurity 放行示例

自定义 WebMvc 拦截器放行

第 6 步（可选）区分环境：只开发环境开启 Swagger

高频踩坑排查清单（重点）

问题 1：打开页面，但一片空白，看不到自己写的接口

问题 2：404 找不到页面

问题 3：实体类返回值不显示注释

问题 4：SpringBoot3 启动报错

补充：如果你执意使用老版本 Swagger2（SpringFox，不推荐）

pom 依赖

配置类

问题 5：本地有 Swagger UI 文件吗

相关攻略

同类更新

热游推荐

精彩专题