API 文档生成工具Knife4j

是的，Knife4j 是基于 Swagger 的增强版 API 文档生成工具，专为 Java 开发者设计（尤其是 Spring Boot 项目），提供更友好的界面和更强的功能。

---

Knife4j 的主要特点

1. 界面美观：比原生 Swagger-UI 更直观，支持多标签、分组管理。
2. 离线文档：支持导出 Markdown、HTML、Word、PDF 等格式。
3. 增强功能：
   • 接口搜索
   • 全局参数设置
   • 接口调试（支持文件上传、自定义请求头等）
   • 动态参数（支持 JSON、XML 示例）
4. 兼容 Swagger 注解：无缝集成 @Api、@ApiOperation 等注解。

---

Spring Boot 集成 Knife4j

1. 添加 Maven 依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version> <!-- 以最新版本为准 -->
</dependency>

2. 配置 Swagger

在 application.yml 或 application.properties 中：

knife4j:
  enable: true
  # 自定义文档信息
  setting:
    language: zh-CN
    enableSwaggerModels: true
    enableDocumentManage: true

3. 创建 Swagger 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;

@Configuration
public class Knife4jConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文档")
                        .version("1.0")
                        .description("Spring Boot 集成 Knife4j"));
    }
}

4. 使用 Swagger 注解

在 Controller 上添加注解：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/user")
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情", description = "根据ID查询用户")
    public User getUser(@PathVariable Long id) {
        return userService.getById(id);
    }
}

---

访问 Knife4j 文档

启动项目后，访问：

http://localhost:8080/doc.html

（默认路径是 /doc.html，原生 Swagger 仍可通过 /swagger-ui.html 访问）

---

高级功能

1. 分组管理
   在配置类中定义多个 GroupedOpenApi Bean，实现不同模块分组显示。

   @Bean
   public GroupedOpenApi userApi() {
       return GroupedOpenApi.builder()
               .group("用户管理")
               .pathsToMatch("/api/user/**")
               .build();
   }
   

2. 离线导出
   在 Knife4j 界面上，点击 “文档管理” → “离线下载”，支持多种格式导出。

3. 全局授权
   支持 JWT、OAuth2 等认证方式，可在配置类中设置：

   @Bean
   public OpenAPI customOpenAPI() {
       return new OpenAPI()
               .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
               .components(new Components()
                       .addSecuritySchemes("BearerAuth",
                               new SecurityScheme()
                                       .type(SecurityScheme.Type.HTTP)
                                       .scheme("bearer")
                                       .bearerFormat("JWT")));
   }
   

---

总结

• Knife4j 比原生 Swagger 更强大，适合企业级 API 文档管理。
• 无缝兼容 Swagger 注解，学习成本低。
• 支持离线导出，方便与团队协作。