Knife4j 功能介绍 ​

Knife4j 是基于 Swagger 的增强工具，专为 Java 项目（尤其是 Spring Boot）提供更强大的 API 文档生成和管理功能。它不仅保留了 Swagger 的核心特性，还增加了许多实用功能，适合企业级开发。

核心功能 ​

1. 强大的 API 文档展示 ​

• 美观的 UI 界面：比原生 Swagger-UI 更直观、易用。
• 离线文档导出：支持导出 HTML、Markdown、Word、PDF 等格式，方便存档或交付。
• 接口搜索：支持按路径、标签、描述快速检索 API。

2. 增强的调试能力 ​

• 在线调试：直接在文档界面发送请求，支持 Header、Cookie、Auth 等参数设置。
• 全局参数：可配置公共请求头（如 Authorization），避免重复填写。
• 响应结果格式化：自动高亮 JSON/XML，支持树形展示。

3. 权限与安全 ​

• 访问控制：可配置 Basic Auth 或 OAuth2，保护文档页面。
• 动态屏蔽敏感接口：通过注解或配置隐藏特定 API（如内部接口）。

4. 代码生成 ​

• 生成客户端代码：支持生成 TypeScript、Java、Curl 等代码片段，方便前端调用。
• Mock 数据：提供模拟数据功能，前端可提前联调。

5. OpenAPI 3.0 支持 ​

• 兼容 Swagger 2.0 & OpenAPI 3.0，适配最新标准。
• 支持更丰富的注解（如 @ApiOperation、@ApiImplicitParam）。

典型使用场景 ​

1. 企业级 API 文档管理 ​

• 适用于 前后端分离 项目，后端开发者维护 API 文档，前端直接查阅。
• 替代传统的 Word 文档，避免文档与代码不同步的问题。

2. 接口调试与测试 ​

• 开发者、测试人员可直接在 Knife4j 界面调试接口，无需依赖 Postman。
• 支持 文件上传、复杂参数（嵌套 JSON） 测试。

3. 项目交付 ​

• 导出 离线文档（Word/PDF）给客户或非技术人员查阅。
• 生成 TypeScript 代码，减少前后端沟通成本。

4. 微服务架构 ​

• 在 Spring Cloud 项目中，Knife4j 可聚合多个服务的 API 文档，统一展示。

快速集成（Spring Boot 示例） ​

1. 添加依赖 ​

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

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

2. 配置 Swagger ​

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文档")
                        .version("1.0")
                        .description("Knife4j 增强文档"));
    }
}

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文档")
                        .version("1.0")
                        .description("Knife4j 增强文档"));
    }
}

3. 访问文档 ​

启动项目后，访问：
🔗 http://localhost:8080/doc.html

对比原生 Swagger ​

总结 ​

✅ 适合人群：Java 开发者、前后端分离团队、需要规范 API 管理的企业。
✅ 推荐场景：替代 Swagger、生成离线文档、在线调试、微服务 API 聚合。
🚀 优势：更美观、更强大、更适合中文用户，是 Swagger 的“增强版”。

如果你的项目在用 Swagger，不妨试试 Knife4j，效率提升明显！ 😊