第十三章 SpringBoot整合knife4j

偏执的太偏执、 2024-04-23 21:03 4阅读 0赞

> 🌹作者主页：青花锁 🌹简介：Java领域优质创作者🏆、Java微服务架构公号作者😄  
> 🌹简历模板、学习资料、面试题库、技术互助
> 
> 🌹文末获取联系方式 📝  
> ![在这里插入图片描述][8e79f79251004be596a5f46b79e5197a.png]

## 系列专栏目录 ##

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

--------------------

## 系列文章目录 ##

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

--------------------

#### 文章目录 ####

*  系列专栏目录
 *  系列文章目录
 *  前言
 *  1、Spring Boot 2
 *   *  1.1、实战案例
     *   *  第一步、创建springBoot项目并且在pom.xml中引入knife4j的依赖包，代码如下：
         *  第二步、创建Swagger配置依赖，代码如下:
         *  第三步、加载静态文件，以及配置了拦截器，放行路径
         *  第四步、新建一个接口Controller类
         *  第五步、访问文档首页
     *  1.2、官方文章案例
     *   *  OpenAPI2
         *  OpenAPI3
 *  2、Spring Boot 3
 *  总结

--------------------

## 前言 ##

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

## 1、Spring Boot 2 ##

### 1.1、实战案例 ###

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

<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即可查看文档

--------------------

## 总结 ##

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

--------------------

### 联系方式 ###

#### 微信公众号：Java微服务架构 ####

![在这里插入图片描述][c8bfb5ed6bbf47f386f48923b2b123ef.jpeg_pic_center]

[8e79f79251004be596a5f46b79e5197a.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/b9304c9e840745f29bd2a2c0296fce69.png
[Java_ _Java]: https://blog.csdn.net/s445320/category_12345409.html
[Aws_ Aws Linux_nginx_git_JDK_Vue]: https://blog.csdn.net/s445320/category_12492968.html
[Java_ Java _Spring Cloud Netflix_Spring Cloud Alibaba_Seata_gateway_shadingjdbc_]: https://blog.csdn.net/s445320/category_12439818.html
[Java_ Java_HashMap_String_StringBuffer_JVM_]: https://blog.csdn.net/s445320/category_12369312.html
[Springboot_ _Springboot_RestFul_Swagger_]: https://blog.csdn.net/s445320/category_12273537.html
[Spring MVC_ _Spring MVC_RestFul_]: https://blog.csdn.net/s445320/category_12295009.html
[_Linux_nginx_git_JDK_Vue_Html_Springboot_Vue_]: https://blog.csdn.net/s445320/category_12426609.html
[Java_ _Java_Selenium_GoogleWebDriver _bing_]: https://blog.csdn.net/s445320/category_8863085.html
[Vue_ _Vue3_axios_Element-ui_]: https://blog.csdn.net/s445320/category_12278346.html
[Spring_ _Spring_Bean_IOC_AOP_jdbcTemplate_redis_]: https://blog.csdn.net/s445320/category_12283629.html
[SpringBoot]: https://blog.csdn.net/s445320/article/details/129921683
[springboot]: https://blog.csdn.net/s445320/article/details/129933138
[springboot 1]: https://blog.csdn.net/s445320/article/details/129949778
[SpringBoot 1]: https://blog.csdn.net/s445320/article/details/129952680
[springboot 2]: https://blog.csdn.net/s445320/article/details/129953402
[Link 1]: https://blog.csdn.net/s445320/article/details/130248527
[springboot 3]: https://blog.csdn.net/s445320/article/details/129958603
[springboot _Druid]: https://blog.csdn.net/s445320/article/details/129989045
[springboot _MyBatis - xml]: https://blog.csdn.net/s445320/article/details/130012383
[_Mybatis plus]: https://blog.csdn.net/s445320/article/details/130130130
[SpringBoot_swagger-bootstrap-ui]: https://blog.csdn.net/s445320/article/details/130419460
[c8bfb5ed6bbf47f386f48923b2b123ef.jpeg_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/f5acb1570c1241a5b97a66b8266f57a8.jpeg