SpringBoot整合knife4j生成Api文档

一、介绍

先看效果

①：Swagger 介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是：

1. 使得前后端分离开发更加方便，有利于团队协作

2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担

3. 功能测试

Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger

②：knife4j介绍

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

二、使用步骤

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

①：引入依赖

        <!-- 导入 knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

②：添加配置类

1.WebMvcConfiguration

@Configuration
public class WebMvcConfiguration {
    /**
     * 加入 knife4j 相关配置  通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("数据统计项目接口文档")
                .version("2.0")
                .description("数据统计项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sanss.djyp.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 设置静态资源映射   设置静态资源映射，否则接口文档页面无法访问
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

③：常用注解使用

1.通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

接下来，使用上述注解，生成可读性更好的接口文档

1.controller层 @Api(tags = "统揽数据回收操作接口")

2.Controller层 @ApiOperation(value = "请求设备信息 xxx 天失败的数据")

3.请求时传递的数据对象
类：@ApiModel(description = "请求接口时传递的数据模型")
属性： @ApiModelProperty(value = "日期（某一天）类型 java.util.Date")

3.请求返回的数据格式
类：@ApiModel(description = "直播返回的数据格式")
属性： @ApiModelProperty(value = "主键值")

三、启动服务

访问：http://localhost:8082/doc.html

四、开启请求头中携带token

①：默认情况下是不能设置请求头的

②：开启动态请求参数

③：效果

④：设置全局参数token