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

news2024/11/25 21:46:08

Knife4j 介绍

Knife4j 官网

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

依赖引入

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

<!-- Knife4j -->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
	<version>4.0.0</version>
</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("1926585708@qq.com")
                        .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;
    }