一、认识 Knife4j1.1 什么是 Knife4jKnife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案前身是 swagger-bootstrap-ui。它并非重新实现一套 OpenAPI 规范而是在 SpringDoc 的基础上提供了更强大的 UI 界面和更多的增强功能。Knife4j 的核心定位可以从两个维度理解前端方面用 Vue Ant Design 重构了整套 UI把原本分散的接口信息重新归类排版。实测响应速度比原生 Swagger 快 40% 左右接口数量超过 50 个时左侧菜单的流畅度差异非常明显。后端方面增加了文档权限控制、接口过滤、离线导出等实用功能还支持基于 Basic 认证的登录访问控制。1.2 Knife4j 与 Swagger / SpringDoc 的关系Knife4j 在 4.0 版本之后基于 SpringDoc 进行了重构因此完全兼容 OpenAPI3 规范。在 Knife4j 中你仍然使用标准的 OpenAPI 注解如Tag、Operation、Parameter等因为 Knife4j 只是增强了 UI 和功能底层规范仍然遵循 OpenAPI。Knife4j 的核心特性包括兼容 OpenAPI 2.0 和 OpenAPI 3.0基础 UI 组件自定义文档、动态参数调试、I18n、接口排序、导出等基于 Springfox Swagger2 规范的自动注入 starter基于 Springdoc-openapi OAS3 规范的自动注入 starter提供对主流网关组件的统一聚合 OpenAPI 接口文档的解决方案适配 Spring MVC、Spring WebFlux、Spring Boot 2.2 ~ 3.01.3 版本适配指南选择正确的版本是成功集成的第一步。以下是根据 Spring Boot 版本选择 Knife4j 的对照表Spring Boot 版本推荐 Knife4j 版本注意事项2.0.x2.0.6需保留 swagger 依赖2.4.x3.0.3开始支持 OpenAPI 3.02.7.x ~ 3.04.x需 JDK173.04.4.0只支持 OpenAPI3JDK ≥ 17重要提醒Knife4j 提供的 starter 已经引用了 springdoc-openapi 的 jar开发者需注意避免 jar 包冲突。二、单体项目快速集成2.1 引入依赖以 Spring Boot 3 OpenAPI3 为例在pom.xml中添加以下依赖dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactIdversion4.4.0/version/dependency如果使用的是 Spring Boot 2.x 且选择 OpenAPI2 规范则使用dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi2-spring-boot-starter/artifactIdversion4.4.0/version/dependency依赖包分析从 Knife4j 4.0 版本开始Knife4j 采用了基于 SpringDoc 的方式。在之前的版本中Knife4j 是基于 SpringFox 的但 SpringFox 已经停止维护因此 Knife4j 转向了 SpringDoc。2.2 配置 OpenAPI引入依赖后还需要创建一个配置类来定义文档的基本信息。以 OpenAPI3 为例importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Info;importorg.springdoc.core.models.GroupedOpenApi;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;ConfigurationpublicclassKnife4jConfiguration{BeanpublicOpenAPIopenAPI(){returnnewOpenAPI().info(newInfo().title(项目API文档).description(基于 Knife4j 的接口文档).version(1.0.0).contact(newio.swagger.v3.oas.models.info.Contact().name(开发者).email(devexample.com)));}BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder().group(用户端接口).pathsToMatch(/api/**).packagesToScan(com.example.controller).build();}}如果使用 OpenAPI2Swagger2规范配置方式如下ConfigurationEnableSwagger2WebMvcpublicclassKnife4jConfiguration{Bean(valuedockerBean)publicDocketdockerBean(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(newApiInfoBuilder().description(# Knife4j RESTful APIs).contact(xiaoyminfoxmail.com).version(1.0).build()).groupName(用户服务).select().apis(RequestHandlerSelectors.basePackage(com.github.xiaoymin.knife4j.controller)).paths(PathSelectors.any()).build();}}2.3 YAML 配置在application.yml中添加配置# springdoc-openapi 项目配置springdoc:swagger-ui:path:/swagger-ui.htmltags-sorter:alphaoperations-sorter:alphaapi-docs:path:/v3/api-docsgroup-configs:-group:defaultpaths-to-match:/**packages-to-scan:com.example.controller# knife4j 的增强配置不需要增强可以不配knife4j:enable:truesetting:language:zh_cn2.4 编写接口注解使用 OpenAPI3 规范注解注释 REST 接口示例代码如下RestControllerRequestMapping(body)Tag(namebody参数)publicclassBodyController{Operation(summary普通body请求)PostMapping(/body)publicResponseEntityFileRespbody(RequestBodyFileRespfileResp){returnResponseEntity.ok(fileResp);}Operation(summary普通body请求ParamHeaderPath)Parameters({Parameter(nameid,description文件id,inParameterIn.PATH),Parameter(nametoken,description请求token,requiredtrue,inParameterIn.HEADER),Parameter(namename,description文件名称,requiredtrue,inParameterIn.QUERY)})PostMapping(/bodyParamHeaderPath/{id})publicResponseEntityFileRespbodyParamHeaderPath(PathVariable(id)Stringid,RequestHeader(token)Stringtoken,RequestParam(name)Stringname,RequestBodyFileRespfileResp){fileResp.setName(fileResp.getName(),receiveName:name,token:token,pathID:id);returnResponseEntity.ok(fileResp);}}2.5 访问文档启动 Spring Boot 项目后浏览器访问 Knife4j 的文档地址http://localhost:8080/doc.html三、常用注解详解3.1 OpenAPI3 注解推荐自 Knife4j 4.0 起推荐使用 OpenAPI3 标准注解与底层规范保持一致避免后续切换文档系统时的不兼容问题。注解作用位置说明TagController 类描述一组接口的分类名称Operation方法描述单个接口的摘要、描述Parameter方法参数描述请求参数的信息Parameters方法组合多个ParameterSchema实体类/字段描述实体类及字段的含义ApiResponse方法描述单个响应ApiResponses方法描述多个响应Schema的使用示例Schema(description用户信息)publicclassUserVO{Schema(description用户ID,example1)privateLongid;Schema(description用户名,example张三,requiredModeSchema.RequiredMode.REQUIRED)privateStringusername;Schema(description邮箱,examplezhangsanexample.com)privateStringemail;}3.2 Swagger2 注解旧版如果使用 OpenAPI2 规范对应注解如下注解作用位置说明ApiController 类描述 Controller 的作用ApiOperation方法描述一个接口方法ApiParam参数单个参数的描述信息ApiModel实体类用对象接收参数时描述类ApiModelProperty字段描述对象的字段ApiResponse方法HTTP 响应描述ApiIgnore任意忽略该 APIApiImplicitParam方法一个请求参数3.3ApiImplicitParam的属性说明属性取值作用paramTypepath / query / body / header / form查询参数类型dataTypeLong / String 等参数数据类型仅标志说明name字符串接收参数名value字符串参数的意义描述requiredtrue / false参数是否必填defaultValue任意默认值四、Knife4j 增强功能详解4.1 开启增强模式Knife4j 自 2.0.6 版本开始将 UI 界面的个性化配置剥离到后端进行配置。只需在配置文件中设置knife4j:enable:true自 2.0.6 版本后不再需要使用EnableKnife4j注解配置文件中配置knife4j.enabletrue即可。4.2 生产环境屏蔽在部署到生产环境时为了接口安全需要屏蔽所有 Swagger 相关资源。只需在配置文件中配置knife4j:enable:trueproduction:true配置此属性后所有 Swagger 资源包括/doc.html、/v2/api-docs、/swagger-ui.html等都会被屏蔽输出。4.3 访问权限控制Basic 认证Knife4j 提供了简单的 Basic 认证功能只有输入正确的用户名和密码才能访问文档页面knife4j:enable:truebasic:enable:trueusername:adminpassword:123456如果开启了 Basic 认证功能但未配置用户名及密码Knife4j 提供了默认的用户名和密码admin/123321。4.4 自定义主页内容Knife4j 自 2.0.8 版本开始开发者可以提供一个 Markdown 文件来自定义显示 Home 主页的内容knife4j:enable:truesetting:enable-footer:falseenable-footer-custom:truefooter-custom-content:Copyright © 2026 My Company4.5 自定义 Host在 Knife4j 2.0.4 版本新增了 Host 个性化配置方便在文档部署后针对不同的网络环境进行调试knife4j:enable:truesetting:enable-host:falseenable-host-text:重要提醒使用此属性时服务端必须开启跨域配置。自 Knife4j 4.0 版本开始使用knife4j-openapi3-spring-boot-starter组件时不需要额外配置而使用knife4j-openapi2-spring-boot-starter组件时则需要。4.6 参数包含与忽略忽略参数使用ApiOperationSupport中的ignoreParameters属性可以强制忽略不需要显示的参数。包含参数使用includeParameters属性可以强制包含要显示的参数去除多余的参数显示。ApiOperationSupport(order40,includeParameters{ignoreLabels,longUser.ids})ApiOperation(value包含参数值-Form类型1)PostMapping(/ex1c)publicRestIgnoreP1findAllc12(IgnoreP1ignoreP1){RestIgnoreP1rnewRest();r.setData(ignoreP1);returnr;}注意该特性自 Knife4j 4.0 版本后不再提供支持建议使用 OpenAPI3 的标准注解方式。4.7 动态请求/响应参数注释Knife4j 提供了对动态参数的注释功能使用DynamicParameters注解进行说明DynamicResponseParameters用于动态响应参数的注释。4.8 全局参数设置在调试需要认证的接口时可以设置全局参数来自动携带 Token。在 Knife4j UI 界面中点击“文档管理” → “全局参数设置”添加参数例如key Authorizationvalue 请求头 token 信息设置后每次请求都会自动携带该参数避免逐一添加的麻烦。4.9 接口排序Knife4j 支持自定义排序规则。在配置中设置排序规则knife4j:gateway:tags-sorter:orderoperations-sorter:orderalpha默认排序规则按字母序orderKnife4j 提供的增强排序规则开发者可扩展x-order根据数值来自定义排序五、微服务架构下的文档聚合5.1 Spring Cloud Gateway 聚合方案自 4.0 版本后Knife4j 提供了一个针对 Spring Cloud Gateway 网关进行聚合的组件可以轻松聚合各个子服务的 OpenAPI 文档。第一步在网关服务中引入依赖dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-gateway-spring-boot-starter/artifactIdversion4.4.0/version/dependency第二步在网关的application.yml中配置聚合规则Knife4j 支持两种聚合策略手动配置manual和服务发现discover。手动配置模式manualknife4j:gateway:enabled:true# 排序规则tags-sorter:orderoperations-sorter:order# 手动配置模式strategy:manualroutes:-name:用户服务url:/user-service/v2/api-docs?groupdefaultservice-name:user-servicecontext-path:/order:1-name:订单服务url:/order-service/v2/api-docs?groupdefaultservice-name:order-servicecontext-path:/order:2配置属性说明属性类型描述默认值knife4j.gateway.enabledboolean是否开启网关聚合组件falseknife4j.gateway.strategyenum聚合策略manual / discovermanualknife4j.gateway.routes[0].namestring界面显示分组名称nullknife4j.gateway.routes[0].urlstring子服务文档地址-knife4j.gateway.routes[0].service-namestring访问服务名称nullknife4j.gateway.routes[0].orderint排序0knife4j.gateway.routes[0].context-pathstring路由前缀/服务发现模式discoverknife4j:gateway:enabled:truestrategy:discoverdiscover:enabled:trueversion:openapi3注意事项生产环境上线时通过knife4j.gateway.enabled: false关闭避免接口泄漏造成安全问题。服务发现中注意排除网关服务自身。如果网关层面做了鉴权需要把 UI 资源以及相关 API 接口放开。兼容 OpenAPI3 规范聚合时可能丢失 contextPath 属性需由开发者自行配置context-path。配置成功后访问网关地址http://localhost:9002/doc.html即可看到聚合后的文档页面。六、生产环境最佳实践6.1 环境隔离建议通过 Spring Profile 区分环境配置# application-dev.ymlknife4j:enable:trueproduction:false# application-prod.ymlknife4j:enable:trueproduction:true# 生产环境屏蔽所有文档资源6.2 安全加固启用 Basic 认证在开发/测试环境启用简单的访问认证。网关层白名单将文档相关资源加入网关白名单避免因网关鉴权导致无法访问。生产环境禁用始终在生产环境设置production: true。6.3 版本兼容避坑Spring Boot 2.4.x 项目直接引入最新版 Knife4j 可能导致ClassNotFoundException需根据版本对照表选择适配版本。Knife4j 4.0 以上版本要求 JDK 17Spring Boot 2.x 项目如使用 JDK 8 需选择 4.0 之前的版本。使用 starter 时注意避免与已有 springdoc-openapi 依赖冲突。6.4 接口文档编写规范统一使用 OpenAPI3 注解避免混用 Swagger2 注解以便后续平滑升级。每个 Controller 类添加Tag每个接口方法添加Operation。实体类使用Schema描述字段含义和示例值。善用分组功能通过GroupedOpenApi按业务模块拆分文档。6.5 常用增强配置参考以下是一份完整的企业级配置示例springdoc:api-docs:enabled:truepath:/v3/api-docsswagger-ui:enabled:truepath:/swagger-ui.htmltags-sorter:alphaoperations-sorter:methodtry-it-out-enabled:truepackages-to-scan:-com.example.demo.controllerpaths-to-match:-/api/**global-parameters:-name:Authorizationdescription:Bearer Token 认证in:headerrequired:falseschema:type:stringknife4j:enable:truesetting:language:zh_cnenable-footer:trueenable-footer-custom:truefooter-custom-content:Copyright © 2026 My Companybasic:enable:false七、总结Knife4j 作为国产 API 文档增强工具在 Swagger/OpenAPI 生态中提供了更优秀的 UI 体验和更丰富的实用功能。本教程覆盖了从基础集成到微服务聚合的完整知识体系核心要点如下版本选择是关键根据 Spring Boot 版本选择匹配的 Knife4j 版本4.0 基于 SpringDoc OpenAPI3要求 JDK 17。注解写规范推荐统一使用 OpenAPI3 标准注解Tag、Operation、Schema与底层规范一致。增强功能按需开启生产环境屏蔽、Basic 认证、全局参数、自定义主页等功能通过 YAML 配置即可启用。微服务聚合通过knife4j-gateway-spring-boot-starter在网关层聚合所有子服务的文档支持手动配置和服务发现两种模式。生产环境安全第一务必配置production: true或通过 Profile 隔离确保文档不会在生产环境暴露。如需深入了解可参考 Knife4j 官方文档https://doc.xiaominfo.com/