企业官网建设流程全解析

一、认识 Knife4j

1.1 什么是 Knife4j

Knife4j 是一个集 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.0

1.3 版本适配指南

选择正确的版本是成功集成的第一步。以下是根据 Spring Boot 版本选择 Knife4j 的对照表：

重要提醒：Knife4j 提供的 starter 已经引用了 springdoc-openapi 的 jar，开发者需注意避免 jar 包冲突。

二、单体项目快速集成

2.1 引入依赖

以 Spring Boot 3 + OpenAPI3 为例，在pom.xml中添加以下依赖：

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

如果使用的是 Spring Boot 2.x 且选择 OpenAPI2 规范，则使用：

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.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("dev@example.com")));}@BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder().group("用户端接口").pathsToMatch("/api/**").packagesToScan("com.example.controller").build();}}

如果使用 OpenAPI2（Swagger2）规范，配置方式如下：

@Configuration@EnableSwagger2WebMvcpublicclassKnife4jConfiguration{@Bean(value="dockerBean")publicDocketdockerBean(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(newApiInfoBuilder().description("# Knife4j RESTful APIs").contact("xiaoymin@foxmail.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:'default'paths-to-match:'/**'packages-to-scan:com.example.controller# knife4j 的增强配置，不需要增强可以不配knife4j:enable:truesetting:language:zh_cn

2.4 编写接口注解

使用 OpenAPI3 规范注解注释 REST 接口，示例代码如下：

@RestController@RequestMapping("body")@Tag(name="body参数")publicclassBodyController{@Operation(summary="普通body请求")@PostMapping("/body")publicResponseEntity<FileResp>body(@RequestBodyFileRespfileResp){returnResponseEntity.ok(fileResp);}@Operation(summary="普通body请求+Param+Header+Path")@Parameters({@Parameter(name="id",description="文件id",in=ParameterIn.PATH),@Parameter(name="token",description="请求token",required=true,in=ParameterIn.HEADER),@Parameter(name="name",description="文件名称",required=true,in=ParameterIn.QUERY)})@PostMapping("/bodyParamHeaderPath/{id}")publicResponseEntity<FileResp>bodyParamHeaderPath(@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 标准注解，与底层规范保持一致，避免后续切换文档系统时的不兼容问题。

@Schema的使用示例：

@Schema(description="用户信息")publicclassUserVO{@Schema(description="用户ID",example="1")privateLongid;@Schema(description="用户名",example="张三",requiredMode=Schema.RequiredMode.REQUIRED)privateStringusername;@Schema(description="邮箱",example="zhangsan@example.com")privateStringemail;}

3.2 Swagger2 注解（旧版）

如果使用 OpenAPI2 规范，对应注解如下：

3.3@ApiImplicitParam的属性说明

四、Knife4j 增强功能详解

4.1 开启增强模式

Knife4j 自 2.0.6 版本开始，将 UI 界面的个性化配置剥离到后端进行配置。只需在配置文件中设置：

knife4j:enable:true

自 2.0.6 版本后，不再需要使用@EnableKnife4j注解，配置文件中配置knife4j.enable=true即可。

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 Company"

4.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(order=40,includeParameters={"ignoreLabels","longUser.ids"})@ApiOperation(value="包含参数值-Form类型1")@PostMapping("/ex1c")publicRest<IgnoreP1>findAllc12(IgnoreP1ignoreP1){Rest<IgnoreP1>r=newRest<>();r.setData(ignoreP1);returnr;}

注意：该特性自 Knife4j 4.0 版本后不再提供支持，建议使用 OpenAPI3 的标准注解方式。

4.7 动态请求/响应参数注释

Knife4j 提供了对动态参数的注释功能，使用@DynamicParameters注解进行说明，@DynamicResponseParameters用于动态响应参数的注释。

4.8 全局参数设置

在调试需要认证的接口时，可以设置全局参数来自动携带 Token。在 Knife4j UI 界面中：

1. 点击“文档管理” → “全局参数设置”
2. 添加参数，例如：
   • key =Authorization
   • value = 请求头 token 信息

设置后，每次请求都会自动携带该参数，避免逐一添加的麻烦。

4.9 接口排序

Knife4j 支持自定义排序规则。在配置中设置排序规则：

knife4j:gateway:tags-sorter:orderoperations-sorter:order

• alpha：默认排序规则，按字母序
• order：Knife4j 提供的增强排序规则，开发者可扩展x-order，根据数值来自定义排序

五、微服务架构下的文档聚合

5.1 Spring Cloud Gateway 聚合方案

自 4.0 版本后，Knife4j 提供了一个针对 Spring Cloud Gateway 网关进行聚合的组件，可以轻松聚合各个子服务的 OpenAPI 文档。

第一步：在网关服务中引入依赖

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-gateway-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

第二步：在网关的application.yml中配置聚合规则

Knife4j 支持两种聚合策略：手动配置（manual）和服务发现（discover）。

手动配置模式（manual）：

knife4j:gateway:enabled:true# 排序规则tags-sorter:orderoperations-sorter:order# 手动配置模式strategy:manualroutes:-name:用户服务url:/user-service/v2/api-docs?group=defaultservice-name:user-servicecontext-path:/order:1-name:订单服务url:/order-service/v2/api-docs?group=defaultservice-name:order-servicecontext-path:/order:2

配置属性说明：

服务发现模式（discover）：

knife4j: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 17+，Spring 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 Company"basic:enable:false

七、总结

Knife4j 作为国产 API 文档增强工具，在 Swagger/OpenAPI 生态中提供了更优秀的 UI 体验和更丰富的实用功能。本教程覆盖了从基础集成到微服务聚合的完整知识体系，核心要点如下：

1. 版本选择是关键：根据 Spring Boot 版本选择匹配的 Knife4j 版本，4.0+ 基于 SpringDoc + OpenAPI3，要求 JDK 17+。
2. 注解写规范：推荐统一使用 OpenAPI3 标准注解（@Tag、@Operation、@Schema），与底层规范一致。
3. 增强功能按需开启：生产环境屏蔽、Basic 认证、全局参数、自定义主页等功能通过 YAML 配置即可启用。
4. 微服务聚合：通过knife4j-gateway-spring-boot-starter在网关层聚合所有子服务的文档，支持手动配置和服务发现两种模式。
5. 生产环境安全第一：务必配置production: true或通过 Profile 隔离，确保文档不会在生产环境暴露。

如需深入了解，可参考 Knife4j 官方文档：https://doc.xiaominfo.com/