Spring Boot集成Swagger/Knife4j

1、Swagger

Swagger：开源框架，用于描述、消费和可视化 RESTful Web 服务。

通过一个标准的接口描述语言，让开发者能够轻松地创建 API 文档。
Swagger 基于 OpenAPI 规范，后者定义了 API 的接口描述格式。

Swagger方式：代码即文档，自动生成文档，代码与文档同步更新。

2、Knife4j（Swagger增强版）集成

Swagger：界面简陋，功能有限
Knife4j（Swagger增强版）：界面美观，功能丰富，支持离线文档

2.1 添加依赖pom.xml

xml 复制代码

<!-- Knife4j（Swagger增强） -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2.2 创建Swagger配置类：Knife4jConfig

java 复制代码

package com.springBoot.hospital.config;

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

import java.util.Collections;
import java.util.List;

@Configuration
@EnableSwagger2
public class Knife4jConfig {

    @Bean
    public Docket createRestApi(){ //Docket：Swagger 的核心配置类，用于定义 API 文档的各种属性。
        return new Docket(DocumentationType.SWAGGER_2) //使用 Swagger 2 规范。
                .apiInfo(apiInfo()) //设置 API 的信息（如标题、描述、版本等），通过调用 apiInfo() 方法获取
                .select() //开始构建 API 选择器，用于选择要生成文档的 API
                //指定扫描 API 控制器的基础包
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())  //包括所有路径的 API
                .build()  //构建 Docket 对象。
                // 添加安全认证
                .securitySchemes(Collections.singletonList(apiKey())) //安全认证方式,使用自定义的 API Key 认证
                .securityContexts(Collections.singletonList(securityContext())); //设置安全上下文,使用自定义
    }

    //设置 API 的信息（如标题、描述、版本等）
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder() //构建 API 信息的构造器
                .title("医院管理系统API文档")
                .description("Spring Boot + MyBatis-Plus + JWT")
                .version("1.0")
                .build(); //完成构建并返回 ApiInfo 实例
    }

    /*
    安全认证方式securityScheme：告诉 Swagger 前端如何收集认证信息，然后在请求头、请求参数等位置发送给后端
    常见方式：
    PI Key（通常在 Header 或 Query 中传递 token）
    HTTP Basic Auth
    OAuth2
    JWT Bearer Token
    */
    //自定义安全认证方式，JWT认证
    private ApiKey apiKey(){  //apiKey()：创建一个 API Key，用于认证
        //        Bearer Token认证（JWT）
//        第一个参数是名称（ "JWT"）， Swagger UI 中认证选择框的名字
//        第二个参数是参数名称（ "Authorization"），请求头的 key
//        第三个参数是参数位置（ "header"），表示 API Key 将在请求头中传递。
        return new ApiKey("JWT","Authorization","header");
    }

    //安全上下文SecurityContext：定义哪些接口需要认证，认证信息如何传递
    private SecurityContext securityContext(){
        //SecurityContext：定义哪些 API 路径需要带上 JWT
        return SecurityContext.builder()
                //设置默认的认证方式，调用 defaultAuth() 方法获取认证信息,设置授权范围
                .securityReferences(defaultAuth())
                .build();
    }

    //默认认证信息，安全引用
    private List<SecurityReference> defaultAuth(){
        //AuthorizationScope：定义授权范围
        AuthorizationScope authorizationScope = new AuthorizationScope("global","accessEverything");
        //创建一个 AuthorizationScope 数组，并将其添加到数组中
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;

        //返回一个包含 SecurityReference 的列表，SecurityReference 中包含了 API Key 的名称（"JWT"）和对应的授权范围
        return Collections.singletonList(new SecurityReference("JWT",authorizationScopes));
    }
}

2.3 在Controller中添加Swagger注解

Swagger注解：

@Api: 用于标记控制器类

tags：为类提供一个分类
description：类的描述信息

@ApiOperation: 描述 API 的具体操作

value：操作的简要描述（必填）
notes：详细描述
response：指定方法返回的类型（通常用于返回类型是自定义对象时）
tags：将该操作归到某个分类下

@ApiParam: 描述方法参数

name：参数的名称（通常与方法参数名一致）
value：参数的简要描述
required：是否为必填项
defaultValue：默认值

@ApiResponse: 描述响应信息

code：响应的状态码
message：响应的简短消息
response：返回的具体类型

2.4 访问Swagger文档

启动应用，访问 http://localhost:8080/doc.html，即可看到接口文档，并支持在页面上测试带Token的接口。

2.5 SpringBoot 整合 Swagger 报错

js 复制代码

Caused by: java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null

这个错误的原因是Swagger与当前使用的Spring Boot版本不兼容。主要出现在Spring Boot 2.6及以后，是Spring Boot 2.6引入的新PathPatternParser导致的。

解决方案 ： Path 匹配策略切换回ant_path_matcher

yml 复制代码

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher