springboot 整合knife4j（绝对可用）1.9.6版~2.0.8版

2023-11-19 21:12:22

1.情景展示

　　开发接口供别人调用或者前后端分离后，前端调后端请求需要提供什么参数，会返回什么样的结果。如果一对一沟通的话，费时费力，写接口文档的话也比较麻烦。

2.效果展示

　　现在使用knife4j就可以实现以下效果：

　　点击调试按钮，就可以直接配置请求参数，发送请求啦

3 1.9.6版本配置

　　这是1.9最后一个版本，要想实现这种效果，实现步骤如下：

　　1.引入jar包

　　只需要引入这一个jar包就可以了，无需其它jar包。　　　　

　　2.创建一个配置类，比如：Knife4jConfig

　　3.导包

　　4.添加注解

　　以上是三个注解，一个都不能少，在这里需要注意的一点就是：

　　启用knif4j使用的注解是：@EnableSwaggerBootstrapUi，而不是@EnableKnife4j

　　5.创建Docket对象，并注入到spring容器当中

　　6.设置主页文档内容

　　在配置文件类Knife4jConfig中添加以上两个方法即可。

4 2.0.4版本配置

　　1.导包

<!--配置knife4j项目接口文档-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

　　说明：2.0.2版本的，只需要把上面jar包的版本号改成2.0.2即可，下面的配置一模一样。

　　只需要引入这一个jar包就可以了，无需其它jar包。　　　　

　　2.创建一个配置类，比如：Knife4jConfig（配置文件类最好创建一个config/conf包，方便统一管理）

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 项目接口文档配置（swagger）
 * @description: 使用knife4j需要一个swagger的配置类
 * @author: Marydon
 * @date: 2020年08月11日 0011 9:22
 */
@Configuration
// 必须启用swagger
@EnableSwagger2
@EnableKnife4j
// swagger文档配置只在指定环境可访问(该注解的值对应的是application.yml文件中的spring.profiles.active的值)
// 支持使用!，比如：!prod表示非生产环境
// @Profile({"dev","test","jc"})
public class Knife4jConfig {
    /*
     * 创建连接的包信息
     * @param: 方法名称随便起，虽然它的名字会被作为Bean对象的名字注入spring容器
     * @date: 2020年08月11日 0011 9:51
     * @param: 
     * @return: springfox.documentation.spring.web.plugins.Docket 返回创建状况
     */
    @Bean
    public Docket defaultApi2() {
        return  new Docket(DocumentationType.SWAGGER_2) // 选择swagger2版本
                .useDefaultResponseMessages(false)
                // 接口文档的基本信息
                .apiInfo(apiInfo())
                .select()
                // 这里指定Controller扫描包路径(项目路径也行)
                // 方式一：配置扫描：所有想要在swagger界面统一管理的接口，都必须在此包下
                // .apis(RequestHandlerSelectors.basePackage("com.company.project.web.controller.entrance"))
                // 方式二：只有当方法上有@ApiOperation注解时，才能生成对应的接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路径使用any风格（指定所有路径）
                .paths(PathSelectors.any())
                .build();

    }

    /*
     * 设置文档信息主页的内容说明
     * @date: 2020年08月11日 0011 9:52
     * @param:
     * @return: springfox.documentation.service.ApiInfo 文档信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口项目 后台服务API接口文档")
                .description("服务相关接口(knife4j)")
                // 服务Url（网站地址）
                .termsOfServiceUrl("http://localhost:8080/")
                .contact(new Contact("Marydon",null,"marydon20170307@163.com"))
                .version("1.0")
                .build();
    }

}

　　启动项目，访问：http://IP:端口号/程序名称/doc.html即可，显示主页。

5.注解基本用法

　　@Api()：用于类的说明，准确的来说用于controller，表示这个类是一个swagger资源

　　对应的是：一个Controller

　　@ApiOperation()：用于方法的说明，表示这是一个HTTP请求

　　对应的是controller里的方法

　　@ApiOperationSupport()：（knife4j增加特性）用于接口方法排序，作者信息描述等

　　@ApiImplicitParams()：参数列表说明

　　如果不是用实体类接收入参的话，存在多个入参可以用该注解说明

　　@ApiParam：对单个参数的说明

　　如果不是用实体类接收入参的话，存在一个或者多个入参也可以用该注解进行逐个说明

　　@ApiModel()：用于描述一个数据模型的信息，即我们常用的实体、VO类、DTO类等描述

　　在接口入参用实体类接收时，通常用该注解对实体类进行说明，一般与@ApiModelProperty结合使用，与上面两个参数注解达到的效果是一样的。

　　@ApiModelProperty()：用于描述数据模型的属性信息

　　对应的是方法名的请求入参

　　@ApiIgnore：自动生成接口说明时忽略，可用于类、方法、方法入参

　　@ApiResponses：响应状态描述（在控制类下方，首个方法名上方）

　　对应到文档上是：

6 2.0.6以后的版本

　　使用该版本，必须使用@EnableSwagger2WebMvc这一个注解。

　　该配置类里的两个方法

　　就可以合并成一个方法啦

@Bean(value = "defaultApi2")
public Docket defaultApi2() {
    Docket docket = new Docket(DocumentationType.SWAGGER_2) // 选择swagger2版本
            // 接口文档的基本信息
            .apiInfo(new ApiInfoBuilder()
                    .title("接口项目 后台服务API接口文档")
                    .description("服务相关接口(knife4j)")
                    // 服务Url（网站地址）
                    .termsOfServiceUrl("http://127.0.0.1:8080/")
                    .contact(new Contact("Marydon",null,"marydon20170307@163.com"))
                    .version("1.0")
                    .build())
            //分组名称，不配置的话，默认值为：default
            .groupName("2.X版本")
            .select()
            // 这里指定Controller扫描包路径(项目路径也行)
            // 方式一：配置扫描：所有想要在swagger界面统一管理的接口，都必须在此包下
            // .apis(RequestHandlerSelectors.basePackage("com.baidu.zhidao.web.controller.entrance"))
            // 方式二：只有当方法上有@ApiOperation注解时，才能生成对应的接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            // 路径使用any风格（指定所有路径）
            .paths(PathSelectors.any())
            .build();
    return docket;
}

　　PS:不合并也是可以哒。　　

　　说明：

　　使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x　

　　需要注意的是：

　　当knife4j<=1.9.6时，它是knife4j的前身，叫做：swagger-bootstrap-ui，必须用注解@EnableSwaggerBootstrapUi+@EnableSwagger2；

　　不仅支持swagger-bootstrap-ui，原始的swagger-ui还是可以使用的，访问地址：

　　http://${host}:${port}/swagger-ui.html