当前位置:

首页 > 编程开发 > SpringBoot集成SpringDocOpenAPI(替代SpringFox/Swagger2)的完整步骤

SpringBoot集成SpringDocOpenAPI(替代SpringFox/Swagger2)的完整步骤

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 风格。 SpringBoot2.x 和 3.x 的依赖版本不一样,下面会标注清楚。 全程步骤式操作,复制就能跑起来。

    前置说明

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

    第 1 步:引入 Ma ven 依赖 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
    

    引入后刷新 Ma ven,等依赖下载完即可。

    第 2 步:创建 Swagger 配置类(可选,用于修改文档标题、描述)

    新建 SwaggerOpenApiConfig.ja va,放在 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集成SpringDocOpenAPI(替代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", ha vingValue = "true")
    public class SwaggerOpenApiConfig {
        // ...代码不变
    }

    application.yml

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

    高频踩坑排查清单(重点!)

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

    1. Controller 必须加 @RestController
    2. 接口方法必须是 public
    3. 启动项目后不要直接访问静态 html,先让 Spring 加载所有 Controller
    4. 检查请求路径是否有统一前缀 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集成SpringDocOpenAPI(替代SpringFox/Swagger2)的完整步骤

    SpringBoot集成SpringDocOpenAPI(替代SpringFox/Swagger2)的完整步骤

    SpringBoot集成SpringDocOpenAPI(替代SpringFox/Swagger2)的完整步骤

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发
    相关文章 更多
    Foxit PDF如何批量提取多个PDF的页面_Foxit PDF跨文件页面提取方法【实战】
    Foxit PDF如何批量提取多个PDF的页面_Foxit PDF跨文件页面提取方法【实战】

    从多个PDF里精准提取指定页面,是文档处理中的常见需求。但如果每个文件要提取的页码不同,或者文件数量一多,手动操作就变得异常繁琐。别担心,这个问题有成熟的解决方案,关键在于根据你的具体场景,选择最趁手的工具和方法。 一、使用福昕PDF编辑器:灵活应对差异化提取 当你需要从不同文件中提取完全不同的页面

    Foxit PDF怎么使用云端服务同步文件_Foxit PDF云文档管理功能教程【指南】
    Foxit PDF怎么使用云端服务同步文件_Foxit PDF云文档管理功能教程【指南】

    遇到福昕PDF的云文档功能“罢工”,文件死活同步不了?别急,这多半是账户登录状态掉了线,或者某个关键开关没打开。下面这份操作指南,能帮你快速打通云端与本地,让文件同步恢复如飞。 一、确认并登录福昕云账户 一切云端操作的前提,都是一个有效的登录状态。如果没登录或者登录失效,云文档功能自然无法使用。 首

    Foxit PDF如何批量添加水印到多个文件_Foxit PDF水印批处理自动化方法【实战】
    Foxit PDF如何批量添加水印到多个文件_Foxit PDF水印批处理自动化方法【实战】

    福昕PDF编辑器提供多种批量添加水印的自动化方案:专业版用户可使用内置图形化工具;技术人员可通过JavaScript脚本调用API实现高级批量处理;系统管理员可结合PowerShell与命令行处理大量文件;个人版用户则可利用软件记忆功能配合快捷键,快速为少量文件依次添加水印。

    Foxit-PDF如何比较两个文件差异-Foxit-PDF文档对比功能使用方法
    Foxit-PDF如何比较两个文件差异-Foxit-PDF文档对比功能使用方法

    在日常工作和学习中,我们常常需要对比两个PDF文件的差异,以便更好地进行文档审核、版本更新等操作。Foxit PDF提供了强大的文档对比功能,让这一过程变得轻松简单。 准备工作 首先,确保你已经安装了Foxit PDF软件。打开软件后,进入主界面。 开启对比功能 在软件界面中,找到“比较”选项。一般

    llama.cpp b12470 修复了哪些 SYCL Flash Attention 掩码广播错误?
    llama.cpp b12470 修复了哪些 SYCL Flash Attention 掩码广播错误?

    llama.cpp b12470 预发布构建修复了 SYCL 后端使用 MKL 的 Flash Attention 路径。掩码按注意力头或批次广播时,会避免对较小掩码维度直接越界读取。

    Qwen Code v0.28.0 默认在哪些场景启用共享 Agent 循环?
    Qwen Code v0.28.0 默认在哪些场景启用共享 Agent 循环?

    Qwen Code v0.28.0 将共享 Agent 循环默认用于无界面会话、Ink 终端和子代理。各入口在没有显式配置时采用自己的默认值。

    n8n 2.49.0 与 3.3.0 预发布版如何保存和隔离工具调用记录?
    n8n 2.49.0 与 3.3.0 预发布版如何保存和隔离工具调用记录?

    n8n 2.49.0 与 3.3.0 预发布版对 AI Agent 作了三处调整。工具调用前的模型文本进入 Agent 历史,每条输入单独保存工具调用历史,一次对话中的每轮工具调用都写入聊天记忆。

    OpenBot v1.1.0-rc.2 的个人版请求需要哪些凭证?
    OpenBot v1.1.0-rc.2 的个人版请求需要哪些凭证?

    OpenBot v1.1.0-rc.2 的个人版请求需要能表明安装身份的凭证。桌面窗口沿用受信任入口建立的会话,程序可携带安装令牌,访问 /api/v2 时还可使用个人 API 密钥。过去直接发出的无凭证请求会被拒绝。

    llama.cpp b12469 的隐式矩阵乘法需要怎样的硬件能力?
    llama.cpp b12469 的隐式矩阵乘法需要怎样的硬件能力?

    llama.cpp b12469 的 Metal CONV_2D 增加隐式 GEMM。能否走新内核取决于设备是否支持 simdgroup 矩阵指令等实际分派条件。

    Google Gerrit Code Review 1.0.0 怎样查看补丁并处理外部审查内容?
    Google Gerrit Code Review 1.0.0 怎样查看补丁并处理外部审查内容?

    Google Gerrit Code Review 1.0.0 安装和只读查询示例,说明主机、工具权限、外部内容及评论投票的确认边界。

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。