再见 Swagger UI！国人开源了一款超好用的 API 文档生成框架，Star 4.7K+，真香！！

背景

最近，栈长发现某些国内的开源项目都使用到了 Knife4j 技术，看名字就觉得很锋利啊！

是不是这样的缩写呢：

Knife4j = Knife for Java ？

Java 匕首？

看起来很牛逼的样子，当然，这是我简单的猜测，从字面上并不能猜到它是干嘛用的！

那么它究竟是一个什么样的框架呢？

Knife4j 简介

Knife4j 的前身是 swagger-bootstrap-ui，其实就是一个纯 Swagger UI 的皮肤项目，用过 Swagger 的应该都知道，Swagger UI 是不怎么好用的，并不太适合国人，所以 swagger-bootstrap-ui 项目就诞生了。

swagger-bootstrap-ui 后面为了满足许多个性化的需求，又加入了许多丰富的服务端特性，不再仅仅只是专注于前端 UI 皮肤了，所以又改名：knife4j。

取名 knife4j 是希望它能像一把匕首一样小巧、轻量，并且功能强悍，更是希望它能成为 Swagger 接口文档服务的通用性增强型解决方案。

Knife4j 由国人程序员萧明于 2017 年开源，到现在已经 4 年多了，看了下 Star 数已经超过 4.7k 了：

Knife4j 还获得了 GVP 项目称号，即 Gitee 最有价值的开源项目，并且我发现现在越来越多的开源项目都在使用它，Swagger UI 可以扔掉了。。

官网地址：

https://doc.xiaominfo.com/knife4j/

开源地址：

https://gitee.com/xiaoym/knife4j

Knife4j 界面赏鉴

Knife4j 采用了 Vue And Design Vue 组件进行重写，相关界面拿出来供大家赏鉴。

接口文档显示界面：

接口调试界面：

Swagger Models 功能：

支持导出离线 Markdown、Html：

knife4j 果然非常强大，整个界面基于左右菜单式的布局方式，支持多标签同时打开展示、切换，文档和调试也更清晰，感觉更符合国人的操作习惯吧。。

Knife4j 实战

knife4j 目前主要支持以 Java 开发为主，并且支持 Spring MVC、Spring Boot、Spring Cloud 框架的集成使用。

本文栈长就以 Spring Boot 为基础实战下吧：

Spring Boot 2.5.0
Knife4j 2.0.9
Maven 3.6.3
JDK 1.8

注意： 使用 Knife4j 2.0.6 版本，Spring Boot 的版本要求 2.2.x

1、Knife4j 依赖引入

代码语言：javascript复制

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

2、Knife4j 配置

开启增强功能及基本的登录认证：

代码语言：javascript复制

knife4j:
  # 开启增强
  enable: true
  # 开启登录认证
  basic:
    enable: true
    username: test
    password: test

支持个性化配置项，如接口地址、接口描述属性、UI 增强等个性化配置功能：

代码语言：javascript复制

/**
 * Knife4j 配置类
 * 来源微信公众号：Java技术栈
 * 作者：栈长
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultDocket")
    public Docket defaultDocket() {
        // 联系人信息
        Contact contact = new Contact("公众号：Java技术栈", "https://www.javastack.cn", "xx@javastack.cn");

        // 创建 Docket
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("Knife4j 测试")
                        .description("Knife4j Test")
                        .termsOfServiceUrl("https://www.javastack.cn")
                        .contact(contact)
                        .version("1.0")
                        .build())
                .groupName("1.x")
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.javastack.springboot.knife4j.api"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

}

Spring Boot 基础就不介绍了，送你一份《Spring ‍Boot 学习笔记》，高清理论＋实战版，照着学习，没有不会的，最新版正在努力更新中，可以持续关注公众号 Java技术栈，会第一时间分享给大家。

3、新增测试接口

新增两个测试接口，一个登录（POST），一个问好（GET）。

代码语言：javascript复制

/**
 * Knife4j 测试接口
 * 来源微信公众号：Java技术栈
 * 作者：栈长
 */
@Api(tags = "测试模块")
@RestController
public class Knife4jController {

    /**
     * Knife4j 测试接口问好
     * 来源微信公众号：Java技术栈
     * 作者：栈长
     */
    @ApiImplicitParam(name = "name", value = "名称", required = true)
    @ApiOperation(value = "公众号Java技术栈向你问好！")
    @ApiOperationSupport(order = 2, author = "栈长")
    @GetMapping("/knife4j/hi")
    public ResponseEntity<String> hello(@RequestParam(value = "name") String name) {
        return ResponseEntity.ok("Hi:"   name);
    }

    /**
     * Knife4j 测试接口登录
     * 来源微信公众号：Java技术栈
     * 作者：栈长
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true),
            @ApiImplicitParam(name = "password", value = "密码", required = true)
    })
    @ApiOperation(value = "接口登录！")
    @ApiOperationSupport(order = 1, author = "栈长")
    @PostMapping("/knife4j/login")
    public ResponseEntity<String> login(@RequestParam(value = "username") String username,
                                        @RequestParam(value = "password") String password) {
        if (StringUtils.isNotBlank(username) && "javastack".equals(password)) {
            return ResponseEntity.ok("登录成功:"   username);
        }
        return ResponseEntity.ok("用户名或者密码有误:"   username);
    }

}

上面为了支持接口顺序和接口作者，使用了 Knife4j 的 @ApiOperationSupport 注解，其他的均为 Swagger 自带的注解，从该目录下看还支持下面的注解：