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