springboot集成swagger之knife4j实战（升级版）

官方文档链接：https://doc.xiaominfo.com/

一、Knifej和swagger-bootstrap-ui对比

Knife4j在更名之前，原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的ui显示，将原来的蓝色变成炫酷的黑色模式；
Knifej是使用knife4j-spring-boot-starter的风格来编写的，可以将配置项写在配置文件中，这些配置项提供了许多增强功能，可以更好的整合springboot、springcloud；
Knifej执行更新，为了更平滑的演进，而swagger-bootstrap-ui已停更；

软件	开发语言&框架	状态	最后版本	风格
Knife4j	Java、JavaScript、Vue	持续更新中	无	1.9.6版本是蓝色，后续版本为黑色
swagger-bootstrap-ui	Java、JavaScript、jQuery	停更	1.9.6	蓝色

二、版本分析

Knife4j底层依赖springfox，因此无需再单独引入Springfox的具体版本，且两者有对应的版本要求，否则会产生很多冲突；
使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x；

版本	说明
1.9.6	蓝色皮肤风格，增加更多后端模块
2.0~2.0.5	Ui重写，蓝色背景变成黑色，底层依赖的springfox框架版本是2.9.2
2.0.6~	底层springfox框架版本升级知2.10.5,OpenAPI规范是v2
3.0~	底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3

三、访问方式：

http://{ip}:{port}/doc.html，访问方式和之前的保持一致，如果项目中配置拦截器等，需要放开doc.html静态资源

四、springboot整合步骤(以2.0.6版本为例，但是也会说明各个版本之间的区别)

(1) 添加依赖

<!-- swagger-ui Knife4j，只需要导入这一个依赖就好了，无需在添加spring-fox的依赖 -->

<dependency>

    <groupId>com.github.xiaoymin</groupId>

    <artifactId>knife4j-spring-boot-starter</artifactId>

    <version>${knife4j.version}</version>

</dependency>

(2) 编写配置

2.0.6及以上版本，使用@EnableSwagger2WebMvc注解开启，而2.0.6之前版本是使用@EnableSwagger2注解，和swagger-bootstrap-ui是一样的；
如果不想编写配置类也可以，将@EnableSwagger2WebMvc标注在启动类上即可，就完成入门级别的整合。

package com.ruyidan.knife4j.config;

import java.util.ArrayList;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.core.env.Environment;

import org.springframework.core.env.Profiles;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

/**

 * @ClassName: SwaggerConfig

 * @Description:

 * @Author: dangbo

 * @Date: 2021/3/31 14:13

 * @Version

 */

@Configuration

@EnableSwagger2WebMvc

// @EnableKnife4j    // 因为在配置文件中配置，因此不需要这个注解了

public class Knife4jConfig {

    @Autowired

    private Environment environment;

    @Bean

    public Docket docket() {

        // 设置显示的swagger环境信息

        Profiles profiles = Profiles.of("dev", "test");

        // 判断是否处在自己设定的环境当中

        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .groupName("分组名称")  // 配置api文档的分组

                .enable(flag)  // 配置是否开启swagger

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.ruyidan")) //配置扫描路径

                .paths(PathSelectors.any()) // 配置过滤哪些

                .build();

    }

    // api基本信息

    private ApiInfo apiInfo() {

        return new ApiInfo("dxiaodang's swagger",

                "测试swagger-ui",

                "v1.0",

                "http://mail.qq.com",

                new Contact("dangbo", "http://mail.qq.com", "145xxxxx@qq.com"),  //作者信息

                "Apache 2.0",

                "http://www.apache.org/licenses/LICENSE-2.0",

                new ArrayList());

    }

}

(3) 访问测试

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

简单入门的springboot整合knife4j就完成了，如果不需要使用增强功能，到此就结束了；后续介绍常用的Kni4j的增强功能！！！

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

(4) 开启增强功能

knife4j 1.9.6版本不支持增强功能；之后的版本才支持增强功能；

knife4j 2.0.6及以上版本，Spring Boot的版本必须大于等于2.2.x，且springfox版本要对应；

（第一步）

使用注解@EnableKnife4j标注；或者在配置文件knife4j.enable=true（2.0.6及以上版本才支持），开启Knife4j增强模式，默认是false；

（第二步）

如果在配置文件中使用个性化文档(knife4j.documents)和个性化设置(knife4j.setting),还需要在创建Docket对象时调用Knife4j提供的扩展Extesions进行赋值
buildExtensions方法需要传入分组名称,该分组名称主要是为了区分开发者在构建自定义文档时，在不同的Docket逻辑分组下进行区别显示

package com.ruyidan.knife4j.config;

import java.util.ArrayList;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.core.env.Environment;

import org.springframework.core.env.Profiles;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

/**

 * @ClassName: SwaggerConfig

 * @Description:

 * @Author: dangbo

 * @Date: 2021/3/31 14:13

 * @Version

 */

@Configuration

@EnableSwagger2WebMvc

@EnableKnife4j

public class Knife4jConfig {

    /*引入Knife4j提供的扩展类*/

    @Autowired

    private OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired

    private Environment environment;

    @Bean

    public Docket docket() {

        // 设置显示的swagger环境信息

        Profiles profiles = Profiles.of("dev", "test");

        // 判断是否处在自己设定的环境当中

        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .groupName("dxiaodang's group")  // 配置api文档的分组

                .enable(flag)  // 配置是否开启swagger

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.ruyidan")) //配置扫描路径

                .paths(PathSelectors.any()) // 配置过滤哪些

                .build()

                // 为了区分开发者在构建自定义文档时，在不同的Docket逻辑分组下进行区别显示

                .extensions(openApiExtensionResolver.buildExtensions("md"));

    }

    // api基本信息

    private ApiInfo apiInfo() {

        return new ApiInfo("dxiaodang's swagger",

                "测试knife4j-ui",

                "v1.0",

                "http://mail.qq.com",

                new Contact("dangbo", "http://mail.qq.com", "145xxxxx@qq.com"),  //作者信息

                "Apache 2.0",

                "http://www.apache.org/licenses/LICENSE-2.0",

                new ArrayList());

    }

}

(5) 编写配置

所有的配置项都在这里，如果说自己使用的版本没有生效，可能就是该版本还未支持，可以升级版本尝试
有些增强功能还需要增加注解：比如增加作者信息，使用@ApiOperationSupport和@ApiSupport
有些增强功能是有默认值的，比如i18n国际化默认为zh_CN，显示OpenAPI规范为true；
有些增强功能是不需要在yml额外配置。只要开始增强功能，就支持，比如导出离线文档，搜索功能；

knife4j:

  enable: true    # 是否开启Knife4j增强模式，默认值为false

  cors: false     # 是否开启一个默认的跨域配置,该功能配合自定义Host使用，默认值为false

  production: false     # 对Knife4j提供的资源提供BasicHttp校验,保护文档

  basic:

    enable: true       # 关闭BasicHttp功能，默认为false

    username: dangbo    # basic用户名

    password: dangbo    # basic密码

  documents:            # 自定义文档集合，该属性是数组

    -

      group: md版本    # 所属分组

      name: 测试分组1    # 类似于接口中的tag,对于自定义文档的分组

      locations: classpath:md/*     # markdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)

    -

      group: markdown版本

      name: 测试分组2

      locations: classpath:markdown/*

  setting:            # 前端Ui的个性化配置属性

    language: en-US                   # Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)，默认为中文

    enableSwaggerModels: true         # 是否显示界面中SwaggerModel功能，默认是true

    enableDocumentManage: true        # 是否显示界面中"文档管理"功能，默认是true

    swaggerModelName: 实体类列表       # 重命名SwaggerModel名称

    enableVersion: false              # 是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点

    enableReloadCacheParameter: false # 是否在每个Debug调试栏后显示刷新变量按钮,默认不显示

    enableAfterScript: true           # 调试Tab是否显示AfterScript功能,默认开启

    enableFilterMultipartApiMethodType: POST    # 具体接口的过滤类型，默认为POST

    enableFilterMultipartApis: false  # 针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址

    enableRequestCache: true          # 是否开启请求参数缓存

    enableHost: false                 # 是否启用Host，默认为false

    enableHostText: 192.168.0.193:8000                # 主机描述

    enableHomeCustom: true            # 是否开启自定义主页内容，默认为false

    homeCustomLocation: classpath:markdown/home.md    # 主页内容Markdown文件路径

    enableSearch: false             # 是否禁用Ui界面中的搜索框，默认为false

    enableFooter: false             # 是否显示Footer，默认为true

    enableFooterCustom: true        # 是否开启自定义Footer，默认为false

    footerCustomContent: Apache License 2.0           # 自定义Footer内容

    enableDynamicParameter: false   # 是否开启动态参数调试功能，默认为false

    enableDebug: true               # 启用调试，默认为true

    enableOpenApi: false            # 显示OpenAPI规范，默认为true

    enableGroup: true               # 显示服务分组，默认为true

(6) 验证增强功能（列举几个，想尝试的朋友可以看看官方文档）

开启登录

默认为英文

支持自定义文档显示

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

如果大家想看Spring Cloud整合Knife4j，可以留言，我花时间整理下分享给大家

本次分享就到这儿了，如果有疑问的话，欢迎大家一起探讨！