SpringBoot轻松实现项目集成Knife4j接口文档

Knife4j 介绍

Knife4j 官网

Knife4j是一款基于Swagger生成API文档的增强工具，它简化了开发者构建和管理RESTful API文档的过程。通过自动扫描项目中的接口信息，Knife4j能够生成详细、易读的API文档，无需手动编写和维护。它提供交互式的接口调试页面，方便验证接口正确性，同时支持接口聚合和分组，便于管理大型项目中的接口。此外，Knife4j还支持Markdown文档，以及定制化配置选项，使得API文档更加美观、灵活和易于展示。总体而言，Knife4j是一款功能强大的工具，能够提升API文档质量和开发效率，推动团队协作和沟通。

依赖引入

Knife4j其实就相当Swagger的升级版，相比于比Swagger要好用多了。

<dependency>
	<groupId>com.github.xiaoymingroupId>
	<artifactId>knife4j-openapi2-spring-boot-starterartifactId>
	<version>4.0.0version>
dependency>

Knife4j 配置类

package com.hsqyz.config.common;

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.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;
import java.util.List;

/**
 * Knife4j 配置
 */
@Configuration
@EnableSwagger2WebMvc // 开启Swagger
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用Swagger
                .enable(true)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(new ApiInfoBuilder()
                        .title("API接口文档")
                		.description("API接口文档描述")
                        .termsOfServiceUrl("http://127.0.0.1:8080/")
                        // 联系方式(这里以本人邮箱为例)
                        .contact("[email protected]")
                        .version("1.0.0")
                        .build()
                )
                // 分组名称
                .groupName("default")
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.hsqyz.controller"))
                // 路径选择器
                .paths(PathSelectors.any())
                .build()
                /**
                 * 设置安全模式，swagger可以设置访问token
                 */
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                .pathMapping("/");
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }


}

版本说明

如果出现错误：

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

图例问题

这里提供两种修复方案

降低Spring Boot 版本到2.6.x以下版本

比如下面版本组合是兼容的

Spring Boot版本	Swagger 版本
2.5.6	2.9.2

SpringBoot版本不降级解决方案

配置文件中加上：

properties 格式

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

yaml 格式

spring:  
  mvc:
    pathmatch:
      matching-strategy=ant_path_matcher

项目运行后，访问ip+端口号+/doc.html，比如：http://localhost:8080/doc.html

全局参数

在实际项目中访问接口都添加了权限，每次访问都要带一个请求头参数token。全局参数就是为了方便传一个固定的参数。当添加全局参数后，所有的接口都会带上该参数。

---

这里介绍2种设置全局参数的方法

第一种 【编码方式】

使用securitySchemes()和securityContexts()来设置

引用代码

/**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

效果：菜单上多了一个Authorize，在参数值中添加上信息

刷新一下，再打开接口就会发现多了个请求头部

第二种 【手动配置全局参数】

直接在菜单文档管理→全局参数设置，然后添加参数：

添加保存

再打开接口就会发现请求头参数加上了

过滤拦截说明

如果使用了安全相关的框架，例如(SaToken，SpringSecurity、包括手动定义的拦截器与过滤器)，可能会拦截到Knife4j的文档接口，导致文档加载失败，需要手动放行这方面的接口

Apifox 一键导入 knife4j 接口文档

点击导入项目

选择Knife4j，填入地址后进行解析

解析出来的地址就是你的分组接口详细信息地址，点击提交即可

参考文章

Spring Boot项目集成Knife4j接口文档的实例代码
knife4j v2.0 用户指南