Knife4j增强版的Swagger UI实现，在Knife4j中提供了很多功能并且用户体验也随之有了很大的提升。Knife4j 主要基于Swagger 2.0构建的，主要的用途就是在SpringBoot项目中用来解决Swagger原生UI某些展示方面的不足，为用户提供了更加直观的接口文档展示功能。

其核心仍然基于Swagger，所以可以与现有的Swagger项目达到一个完美的集成，其用法和配置与Swagger基本上是一致的，在使用的时候只需要引入Knife4j相关的依赖的配置就可以了，下面我们就来看看如何在SpringBoot项目中集成Knife4j

引入依赖

根据上面的介绍，我们首先需要在POM依赖中添加Knife4j和Swagger的相关依赖，如下所示。

<dependencies>
    <!-- Swagger依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    
    <!-- Knife4j依赖 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.9</version>
    </dependency>
</dependencies>

配置 Swagger 和 Knife4j

添加依赖完成之后，接下来就是在SpringBoot项目中添加相关的配置类用来进行Swagger相关的配置，如下所示。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 修改为你的包路径
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档标题")
                .description("API文档描述")
                .version("1.0")
                .build();
    }
}

配置文件

当然除了通过配置类配置之外，我们还可以再SpringBoot的配置文件中添加一些Swagger的基础配置信息，如下所示。

# Spring Boot application configuration
spring.application.name=your-application-name
server.port=8080

# Swagger configuration
knife4j.production=false

如果需要还可以自定义一些Knife4j的配置信息，例如可以在application.properties 中添加如下的一些配置项，如下所示。

# Knife4j 文档标题和描述
knife4j.title=API接口文档
knife4j.description=这是一个使用Knife4j生成的API接口文档
knife4j.version=1.0.0

编写接口并添加注解

接下来就是跟Swagger的用法一样，需要再接口控制器类上添加Swagger的注解，用来生成相应的接口文档。如下所示。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
    @GetMapping("/list")
    public List<String> list() {
        return Arrays.asList("user1", "user2", "user3");
    }
}

访问 Knife4j 文档页面

接下来就是启动项目访问Knife4j的接口文档。这个文档与之前的http://localhost:8080/doc.html

这个文档要比之前Swagger与SwaggerUI增强版的文档要更符合用户体验。看上去也非常的美观。

总结

到这里呢，SpringBoot整合Knife4j就完成了，相比与之前的Swagger2以及Swagger3中增强的UI来讲Knife4j整体的用户体验都是比较好的。并且在使用方面也要比之前的两个API文档工具要更加人性化。最大的优势就在于它可以Swagger进行无缝的集成，有兴趣的读者可以试试。