第十三章 SpringBoot整合knife4j

文章里介绍了Knife4j的OpenAPI2、OpenAPI3规范，以及其支持的Spring Boot版本，同时文章里也加上了大量的实战案例，使得新手也可以很快速的上手，获取UI精美的文档帮助系统。

V红太阳

7573人浏览 · 2024-01-05 09:47:15

V红太阳 · 2024-01-05 09:47:15 发布

🌹作者主页：青花锁 🌹简介：Java领域优质创作者🏆、Java微服务架构公号作者😄
🌹简历模板、学习资料、面试题库、技术互助

🌹文末获取联系方式 📝

系列专栏目录

[Java项目实战] 介绍Java组件安装、使用；手写框架等
 [Aws服务器实战] Aws Linux服务器上操作nginx、git、JDK、Vue等
 [Java微服务实战] Java 微服务实战，Spring Cloud Netflix套件、Spring Cloud Alibaba套件、Seata、gateway、shadingjdbc等实战操作
 [Java基础篇] Java基础闲聊，已出HashMap、String、StringBuffer等源码分析，JVM分析，持续更新中
 [Springboot篇] 从创建Springboot项目，到加载数据库、静态资源、输出RestFul接口、跨越问题解决到统一返回、全局异常处理、Swagger文档
 [Spring MVC篇] 从创建Spring MVC项目，到加载数据库、静态资源、输出RestFul接口、跨越问题解决到统一返回
 [华为云服务器实战] 华为云Linux服务器上操作nginx、git、JDK、Vue等，以及使用宝塔运维操作添加Html网页、部署Springboot项目/Vue项目等
 [Java爬虫] 通过Java+Selenium+GoogleWebDriver 模拟真人网页操作爬取花瓣网图片、bing搜索图片等
 [Vue实战] 讲解Vue3的安装、环境配置，基本语法、循环语句、生命周期、路由设置、组件、axios交互、Element-ui的使用等
 [Spring] 讲解Spring(Bean)概念、IOC、AOP、集成jdbcTemplate/redis/事务等

系列文章目录

第一章 SpringBoot起步
 第二章 springboot 配置文件、多环境配置、运行优先级
 第三章 springboot 统一日志
 第四章 SpringBoot加载静态文件资源
 第五章 springboot 拦截器
 第六章实现自定义全局异常处理
 第七章 springboot 数据库应用
 第八章 springboot 整合Druid
第九章 springboot 整合MyBatis - xml、注解篇
 第十一章整合Mybatis plus
第十二章 SpringBoot整合swagger-bootstrap-ui

前言

SpringBoot整合knife4j，是swagger的升级版本。

1、Spring Boot 2

1.1、实战案例

第一步、创建springBoot项目并且在pom.xml中引入knife4j的依赖包，代码如下：

<!--引入Knife4j的官方start包,该指南选择Spring Boot版本<3.0,开发者需要注意-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

第二步、创建Swagger配置依赖，代码如下:

**
 * 访问地址：http://localhost:8080/doc.html
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //描述字段支持Markdown语法
                        .description("# Knife4j 接口文档")//简介
                        .termsOfServiceUrl("大帅杯")//服务Url
                        .contact("只因你太美")//作者名
                        .version("1.0")//版本
                        .build())
                //分组名称
                .groupName("用户服务")
                .select()
                //这里指定Controller扫描包路径自己的包，不然会是空的
                .apis(RequestHandlerSelectors.basePackage("com.jiangweicong.seckill.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

第三步、加载静态文件，以及配置了拦截器，放行路径

@Configuration
public class MyWebMvcConfig extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //加载public文件夹数据
        registry.addResourceHandler("/public/**")
                .addResourceLocations("classpath:/public/");
        /** 配置knife4j 显示文档 */
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        /** 公共部分内容 */
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    /**
	*一般拦截器是在Bean实例化之前就已经开启，
	*所以当拦截器调用redis工具类或者其他service层的时候会一直显示为null，
	*因为这个时候Bean还未实例化，所以无法调用
    *因此加入拦截器的时候要先用@Bean将拦截器先实例化，再将拦截器进行注册
	*/
    @Bean
    public Interceptor getInterceptor(){
        return new Interceptor();
    }
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(getInterceptor()).addPathPatterns("/**").
                excludePathPatterns("/","*/login","*.html","/images/**","/doc.html","/webjars/**","/swagger-resources","/swagger-resources/**","/v3/**");
    }
}

这里还有一个注意事项就是，用继承WebMvcConfigurationSupport方法的时候千万不能加@EnableWebMVC这个注解，因为我们是用继承的方法所以用该注解的时候他加载的是他本身的实现的内容，而我们自定义的静态文件就都不会加载。或者是直接WebConfig类直接实现WebMvcConfigurer的情况下才能加这个注解

第四步、新建一个接口Controller类

@Api(tags = "登录模块")
@RestController
public class IndexController {
    
    @ApiOperation(value = "登录")
   	@ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", dataType = "String" ),
            @ApiImplicitParam(name = "pwd", value = "密码", paramType = "query", dataType = "int" )
    })
    @PostMapping("/login")
    public String login(@RequestParam(value = "name")String name,
                        @RequestParam(value = "pwd")int pwd){
        String login=name+pwd;
        return login;
    }
}

第五步、访问文档首页

http://localhost:8080/doc.html

1.2、官方文章案例

提示
● Spring Boot 版本建议 2.4.0~3.0.0之间
● Spring Boot 版本 < 2.4 版本则建议选择Knife4j 4.0之前的版本
● Spring Boot 2 + OpenAPI2 demo:knife4j-spring-boot27-demo
● Spring Boot 2 + OpenAPI3 demo:knife4j-springdoc-openapi-demo

OpenAPI2

OpenAPI2(Swagger)规范是Knife4j之前一直提供支持的版本，底层依赖框架为Springfox,此次在4.0版本开始
Knife4j有了新的变化，主要有以下几点：
● Springfox版本选择的依然是2.10.5版本，而并非springfox最新3.0.0版本
● 不支持以Springfox框架为基础的OpenAPI3规范,放弃Springfox项目的后续版本适配支持工作
● Spring Boot 版本建议 2.4.0~3.0.0之间
可以使用 knife4j-openapi2-spring-boot-starter,maven 坐标如下：

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

配置yml属性，如下：

knife4j:
  enable: true
  openapi:
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    # aaa"
    email: xiaoymin@foxmail.com
    concat: 八一菜刀
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.knife4j.demo.new3

最后，访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档

OpenAPI3

OpenAPI3的规范，目前针对Java的Spring Boot项目，主要支持的有2个版本
● springfox 3.0.0：同时兼容OpenAPI2以及OpenAPI3，但是停更很久了
● springdoc-openapi：兼容OpenAPI3规范，更新速度频繁
Knife4j在只有的OpenAPI3规范中，底层基础框架选择springdoc-openapi项目
针对Springfox3.0.0版本会放弃。
建议开发者如果使用OpenAPI3规范的话，也尽快迁移过来。
可以使用 knife4j-openapi3-spring-boot-starter,maven 坐标如下：

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

引入jar包后，同上面的Spring Boot 3版本使用方式一样，进行配置即可。

2、Spring Boot 3

提示
● Spring Boot 3 只支持OpenAPI3规范
● Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
● JDK版本必须 >= 17
● 详细Demo请参考knife4j-spring-boot3-demo
首先，引用Knife4j的starter,Maven坐标如下：

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

Gradle坐标如下：

implementation(“com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.4.0”)

引入之后，其余的配置，开发者即可完全参考springdoc-openapi的项目说明，Knife4j只提供了增强部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启
部分配置如下:

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

Knife4j更多增强配置明细，请移步文档进行查看
最后，使用OpenAPI3的规范注解，注释各个Spring的REST接口，示例代码如下：

@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {

   @Operation(summary = "普通body请求")
   @PostMapping("/body")
   public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok(fileResp);
   }

   @Operation(summary = "普通body请求+Param+Header+Path")
   @Parameters({
           @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
           @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
           @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
   })
   @PostMapping("/bodyParamHeaderPath/{id}")
   public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
       fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
       return ResponseEntity.ok(fileResp);
   }
}

最后，访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档