前言:前面文件已经发过swagger2的整合教程SpringBoot整合swagger，本文主要是介绍knife4j。

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

一、引入相关依赖

        <!--guava 因为springfox-swagger2的高版本中移除了guava的依赖，项目中如果有需要，额外引入guava ，不是必须的-->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>30.1.1-jre</version>
        </dependency>

        <!-- RESTful APIs swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.10.5</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- 解决高版本访问文档时出现java.lang.NumberFormatException: For input string: ""的问题 排除 springfox-swagger2 中的，另外引入-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

        <!--Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

二、加入配置类

import com.fasterxml.classmate.TypeResolver;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.google.common.collect.Lists;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.core.Ordered;
import org.springframework.data.domain.Pageable;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.AlternateTypeRule;
import springfox.documentation.schema.AlternateTypeRuleConvention;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.sql.Timestamp;
import java.util.List;

import static springfox.documentation.schema.AlternateTypeRules.newRule;

/**
 * Swagger配置类
 *
 * @author zhuheguo
 * @date 2021/04/07 11:06
 */
@Configuration
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
@EnableSwagger2WebMvc
public class SwaggerDataConfig {

    @Value("${swagger.enabled}")
    private Boolean enabled;

    @Value("${swagger.title}")
    private String title;

    @Value("${swagger.version}")
    private String version;

    @Value("${swagger.serverUrl}")
    private String serverUrl;

    @Value("${swagger.contact.author}")
    private String contact_author;

    @Value("${swagger.contact.url}")
    private String contact_url;

    @Value("${swagger.contact.email}")
    private String contact_email;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enabled)
                .apiInfo(
                        new ApiInfoBuilder()
                                .title(title)
                                .description(title)
                                .termsOfServiceUrl(serverUrl)
                                .version(version)
                                .contact(new Contact(contact_author, contact_url, contact_email))
                                .build()
                )
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                // 将timestamp类型的请求参数以string的类型接收
                .directModelSubstitute(Timestamp.class, String.class)
                ;
    }

    /**
     * 将Pageable转换展示在swagger中
     *
     * @param resolver
     * @return
     */
    @Bean
    public AlternateTypeRuleConvention pageableConvention(final TypeResolver resolver) {
        return new AlternateTypeRuleConvention() {
            @Override
            public int getOrder() {
                return Ordered.HIGHEST_PRECEDENCE;
            }

            @Override
            public List<AlternateTypeRule> rules() {
                return Lists.newArrayList(newRule(resolver.resolve(Pageable.class), resolver.resolve(Page.class)));
            }
        };
    }

    @ApiModel
    @Data
    private static class Page {
        @ApiModelProperty("页码 (1..N)")
        private Integer page;

        @ApiModelProperty("每页显示的数目")
        private Integer size;

        @ApiModelProperty("以下列格式排序标准：property[,asc | desc]。 默认排序顺序为升序。 支持多种排序条件：如：id,asc")
        private List<String> sort;
    }
}

三、配置文件

#是否开启 swagger-ui
swagger:
  enabled: true
  title: 未来立体教学平台 RESTful APIs 接口文档
  serverUrl:
  version: 1.0

  contact:
    author: zhuHeguo
    url:  www.ovozz.com
    email:  zhg_job@163.com

#是否knife4j增强配置
knife4j:
  enable: true
  #是否开启访问文档账号密码
  basic:
    enable: false
    username: admin
    password: admin

四、扩展
文档示例：http://knife4j.xiaominfo.com/doc.html#/home
官方文档：https://gitee.com/xiaoym/knife4j
js扩展：https://gitee.com/xiaoym/knife4j/wikis/AfterScript