尧图网络 高端网站定制 · 原创设计
免费咨询热线
400-888-6620
免费获取方案
Spring Boot 整合 Swagger2 和 Knife4j实现接口文档与可视化调试
文章目录一、Swagger2Springfox核心依赖与配置1.1 导入依赖1.2 配置类1.3 Spring Boot 2.6 兼容处理1.4 跨模块引用配置二、常用注解2.1 注解实例三、Knife4j 整合3.1 导入依赖3.2 配置文件3.3 访问与鉴权总结后端开发中接口文档的维护一直是痛点——代码变了文档没更新、手动编写效率低、调用方总要问参数格式。Swagger2基于 Springfox 实现通过注解自动生成 API 文档Knife4j 在其基础上提供更清爽的 UI 和更强的调试能力。本文从依赖配置到注解使用覆盖 Swagger2 Knife4j 的完整集成流程。一、Swagger2Springfox核心依赖与配置1.1 导入依赖dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version/dependencydependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version/dependency1.2 配置类ConfigurationEnableSwagger2publicclassSwaggerConfiguration{BeanpublicDocketbuildDocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(buildApiInfo()).select().apis(RequestHandlerSelectors.basePackage(com.mbqm)).paths(PathSelectors.any()).build().globalOperationParameters(getParameterList());}privateApiInfobuildApiInfo(){returnnewApiInfoBuilder().title(平台管理 API 文档).description(平台管理服务 api).contact(newContact(小Ti客栈,,)).version(1.0.0).build();}privateListParametergetParameterList(){ParameterBuilderbuildernewParameterBuilder();ListParameterparamsnewArrayList();params.add(builder.name(Authorization).description(token 认证).modelRef(newModelRef(string)).parameterType(header).required(false).build());returnparams;}}关键说明RequestHandlerSelectors.basePackage(com.mbqm)指定扫描的 Controller 包路径微服务中每个服务各配自己的包globalOperationParameters用于全局添加请求头参数如 token避免每个接口重复定义buildApiInfo配置文档标题、描述、联系人、版本号。1.3 Spring Boot 2.6 兼容处理Spring Boot 2.6 起默认路径匹配从 AntPathMatcher 切换为 PathPatternParser与 Springfox 不兼容需回退spring:mvc:pathmatch:matching-strategy:ant-path-matcher1.4 跨模块引用配置如果 Swagger 配置类放在公共模块如common业务模块需通过ComponentScan引入ConfigurationComponentScan(com.heima.common.swagger)publicclassSwaggerConfig{}启动后访问http://localhost:8080/swagger-ui.html即可看到文档页面。二、常用注解注解作用位置作用ApiController 类描述模块作用ApiOperation接口方法描述接口用途ApiImplicitParam接口方法描述单个请求参数ApiImplicitParams接口方法描述多个请求参数ApiParam方法参数描述参数的约束信息ApiModel请求/响应实体类描述实体ApiModelProperty实体字段描述字段含义ApiIgnore方法或类忽略该接口不出现在文档中ApiResponse接口方法描述响应信息ApiResponses接口方法描述整体响应2.1 注解实例RestControllerRequestMapping(/api/v1/channel)Api(tags频道管理 API)publicclassWmChannelController{AutowiredprivateIWmChannelServicewMChannelService;PostMapping(/list)ApiOperation(value根据名称模糊查询分页列表,notes频道名称模糊匹配)ApiImplicitParam(namedto,value查询对象,requiredtrue,dataTypeChannelDto)publicResponseResultlistByName(RequestBodyChannelDtodto){returnwMChannelService.listByName(dto);}}DTO 实体DataEqualsAndHashCode(callSupertrue)publicclassChannelDtoextendsPageRequestDto{ApiModelProperty(value频道名称)privateStringname;}三、Knife4j 整合Knife4j 是 Swagger 的增强 UI 工具包界面更现代支持离线文档、全局参数调试、请求缓存等。3.1 导入依赖Swagger2 版本使用 Knife4j 专用启动器dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.3/version/dependencySwagger 原有的配置类无需改动Knife4j 自动兼容。3.2 配置文件knife4j:enable:truesetting:language:zh_cnswagger-model-name:应用名称3.3 访问与鉴权启动后访问http://localhost:8080/doc.html相比原生 Swagger UI接口分组左侧树形展示层次更清晰右侧参数调试支持全局参数如 token支持请求缓存同一接口多次调试不必重复填参数。生产环境关闭文档暴露knife4j:basic:enable:trueusername:adminpassword:adminproduction:trueenable:true开启 basic 鉴权后访问/doc.html需输入用户名密码production: true使接口列表不可见防止生产环境泄露。总结组件职责springfox-swagger2通过注解生成 Swagger2 规范 JSONspringfox-swagger-uiSwagger 原生 UI/swagger-ui.htmlknife4j增强 UI 更多调试功能/doc.html开发阶段用 Knife4j 提升调试效率生产环境开启productiontrue basic 鉴权防暴露。需要注意的是 Springfox 已停维新项目建议直接使用 springdoc-openapiOpenAPI 3迁移成本不高。文章结束喜欢就给个一键三连吧你的肯定是我最大的动力点赞上一千我就是脑瘫也出下章。
RELATED

相关推荐

医疗影像分割边界优化:MONAI框架实战解析

医疗影像分割边界优化:MONAI框架实战解析

1. 医疗影像分割的精细化挑战与MONAI解决方案医疗影像分割一直是计算机辅助诊断中的核心环节,特别是在肿瘤识别、器官划分等场景中,分割边界的精度直接影响临床决策。传统分割方法(如阈值法、区域生长法)在复杂组织边界处常出现锯…

📅 2026/10/25 15:35:07
Vue 3中nextTick()的原理与应用场景

Vue 3中nextTick()的原理与应用场景

1. 为什么需要 nextTick()?在 Vue 3 的响应式系统中,数据变化到 DOM 更新并不是同步进行的。Vue 会将多个数据变更收集起来,在下一个事件循环中批量更新 DOM。这种异步更新机制能有效避免不必要的重复渲染,提升性能。但这也带来了…

📅 2026/10/15 11:06:36
WebSocket协议详解:从原理到实战优化

WebSocket协议详解:从原理到实战优化

1. WebSocket协议的本质:从HTTP的局限说起2008年,当Ian Hickson和Michael Carter提出WebSocket协议时,他们正在解决一个困扰实时Web应用多年的核心问题:HTTP协议在双向通信场景下的先天不足。传统HTTP采用"一问一答"的请…

📅 2026/10/27 16:29:38
MORE NEWS

更多资讯

📰

电工证在哪复审的?洛阳应届生必看,考前押题这样用最稳妥

电工证在哪复审的?洛阳应届生必看,考前押题这样用最稳妥 怕考不过白交培训费,你不是一个人。今年洛阳有超过2000名工程类毕业生在打听“电工证在哪复审的”,但真正了解流程的人却寥寥无几。别急,这期内容专门为你整理了从报考、复审到考试技巧的全套…

📰

保定电工证复审电话报名费多少钱多久拿证

保定电工证复审电话报名费多少钱多久拿证 学历不高怕报不上名?保定电工证复审电话怎么找?多久拿证?别担心,咱们一步一步来,不搞虚的。 你是不是也在担心,自己学历不够,连电工证都报不上?其实,…

📰

电工作业回家标准多少钱?考个证就能找到好工作

电工作业回家标准多少钱?考个证就能找到好工作 现在找工作,没有特种作业证,连门都进不去。尤其是电工作业,几乎每个工地、工厂都需要持证上岗。如果你正在考虑考电工证,又担心 多少钱…

📰

佛山考初级电工证官方回应:怕考不过白交培训费?这几点你必须知道

佛山考初级电工证官方回应:怕考不过白交培训费?这几点你必须知道 怕考不过白交培训费?佛山考初级电工证最近被很多学员问到,尤其是刚毕业的工程类学生,像洛阳涧西区的应届生,都想尽快拿到证去实习或者找工作。不过,很多人担心的是,花了几千块培训费,…

📰

电工证四表人识在哪考怎么考一次过

电工证四表人识在哪考怎么考一次过 实操考试心里没底怕挂科,尤其是面对【电工证四表人识】的实操考核,很多人觉得这关最难。其实,只要提前准备,了解流程,掌握技巧,一次通过并不是难事。特别是如果你在洛阳涧西区劳务班组工作,这份证书几乎是“敲门砖”…

📰

扬州哪里报考电工证千万别踩坑 工地太忙根本没时间复习考试

扬州哪里报考电工证千万别踩坑 工地太忙根本没时间复习考试 工地太忙根本没时间复习考试,这几乎是每个电工从业者都面临的真实问题。特别是对于周口劳务班组负责人来说,一边要管理施工进度,一边还要兼顾员工的证书办理,稍有不慎就可能耽误项目,甚至影响…

TODAY

今日更新

THIS WEEK

本周精选

THIS MONTH

本月热门

读完文章,想聊聊您的网站?

告诉我们您的行业与需求,资深顾问一对一梳理方案与报价,全程免费。

📞 💬