本文已参与「新人创作礼」活动，一起开启掘金创作之路

前言

在日常的开发工作中，往往需要向前端提供接口文档。但是编写文档的维护成本很高，所以现在有一些开发者开发了自动生成在线接口文档的pom依赖，本篇文章介绍一下比较常用的knife4j。
可能有很多前端同学现在已经使用knife4j进行接口对接了，我们介绍一下Spring Boot如何集成knif4j。

集成knife4j

引入依赖

在pom.xml中添加依赖如下

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

修改项目配置文件

因为我们使用的时Spring Boot 2.6+,knife4j start的依赖有些不兼容，这里我们先通过修改配置文件的方式，使其兼容起来，现在配置文件内容如下

server:
  port: 1001
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

添加配置文件

我们需要编写一个配置类，使knife4j生效。在boot下新建/config/knife4j文件夹，下边新建Knife4jConfiguration.java内容如下

package code.liang.top.admin.boot.config.knife4j;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

/**
 * @author lmh
 * @version 1.0
 * @description: knife4j config
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact(getContact())
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("code.liang.top.admin.boot.modules"))
                .paths(PathSelectors.any())
                .build();
    }
    private Contact getContact(){
        return new Contact("lmh","","");
    }
}

看到这里你可能会有疑问：为什么knife4j的依赖我们写的大部分是swagger，其实knife4j就是有swagger升级而来的。在这里边其他的设置可以按照自己的现实情况设置自己的配置，注意需要看一下RequestHandlerSelectors.basePackage("code.liang.top.admin.boot.modules")这里的配置，它指定了我们的扫描路径

编写一个测试接口

我们在这里直接修改上一篇写的index接口，编写内容如下

package code.liang.top.admin.boot.modules.index.controller;

import code.liang.top.admin.boot.commom.entity.ResVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author lmh
 * @version 1.0
 * @description: index controller
 */
@Api(tags = "index")
@RestController
@RequestMapping
public class IndexController {
    @RequestMapping("/index")
    @ApiOperation(value = "index方法")
    @ApiImplicitParam(name = "name",value = "姓名")
    public ResVo<String> index(@RequestParam(required = false,defaultValue ="default")String name) {
        return ResVo.ok("Hello "+name);
    }
}

这里我们解释一下添加的注解

@Api(tags = "index") 说明这个controller的标签为index
@ApiOperation(value = "index方法") 说明了这个接口是index方法
@ApiImplicitParam(name = "name",value = "姓名") 接受name参数，它代表姓名属性
@RequestParam(required = false,defaultValue ="default")String name 这个参数不是必填的，如果不填默认值是default
然后我们重启项目，访问 http://127.0.0.1:1001/doc.html 显示如下，我们可以看到能正常访问到knife4j首页了。

关于响应数据

我们已经定义好一个在线调用的接口了，有没有方式能设置显示返回的数据代表的属性呢？答案是有的。我们先把基本的响应实体ResVo修改如下

...
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
...
@Data
@Accessors(chain = true)
@ApiModel("基本返回属性")
public class ResVo<T> implements Serializable {
    @Serial
    private static final long serialVersionUID = 5147155156059020583L;
    @ApiModelProperty("响应码")
    private int code;
    @ApiModelProperty("响应信息")
    private String msg;
    @ApiModelProperty("返回data")
    private T data;
    @ApiModelProperty("是否成功标识")
    private boolean success;
    ...

这里我省略了一些重复代码，简单讲一下这些注解的意思吧

@ApiModel("基本返回属性") 定义当前的返回实体为基本返回属性
@ApiModelProperty("响应码") 定义code的返回属性是响应码我们重启一下项目，刷新首页，即可看到最新的返回属性注释调用接口也是我们预期的返回
至此我们已经集成完成了knife4j

结语

这篇文章我们完成了集成knife4j，极大的节省了接口文档的维护工作。
本文所有代码已上传的gitee,欢迎有兴趣的掘友们startgitee.com/liangminghu…
欢迎关注我的掘金账号:juejin.cn/user/261290…
下期预告：整合mybatis plus，开发第一个增删改查功能

从头开始开发一个java后端项目：3集成在线接口调试文档

前言