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迁移成本不高。文章结束喜欢就给个一键三连吧你的肯定是我最大的动力点赞上一千我就是脑瘫也出下章。

Spring Boot 整合 Swagger2 和 Knife4j实现接口文档与可视化调试

相关推荐

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

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

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

更多资讯

从零开始用ESP32+HC-SR501实现人体感应：接线、代码与避坑指南

网页视频下载教程：猫抓三步保存任意网页视频完整指南

ToF相机全链路实战：从光子计时到ROS2深度流稳定输出

六轴机械臂正逆运动学仿真：基于Qt/C++的工程化实现

智能论文写作工具：NLP技术如何提升学术写作效率

常用控件的介绍（下）

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？