SpringBoot中整合knife4j接口文档的实践

所属分类：软件编程 / java 阅读数： 175

收藏 0赞 0分享

在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护

接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护

一、界面先赏

1、首页

2、接口文档

3、调试

二、整合 knife4j

1、引入 maven 依赖

<!-- knife4j接口文档 start -->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.2</version>
</dependency>
<!-- 避免版本冲突 -->
<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>29.0-jre</version>
</dependency>

一般情况我们只需要引入 knife4j 的依赖即可，但是有时会出现 guava 的版本冲突，所以，我们把 guava 一起引入进来

2、knife4j 配置文件

创建 Knife4jConfig 文件

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

/**
 * knife4j 配置
 *
 * @Author Lizhou
 */
@Configuration
@EnableSwagger2
public class Knife4jConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.zyxx"))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("SpringBoot项目 后台服务API接口文档")
        .description("使用 knife4j 搭建的后台服务API接口文档")
        .termsOfServiceUrl("http://localhost:8080/")
        .contact("lizhou")
        .version("1.0.0")
        .build();
  }
}

整体配置与 Swagger2 几乎一致，扫描 controller 所在的包

3、启动类

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

/**
 * knife4j 配置
 *
 * @Author Lizhou
 */
@Configuration
@EnableSwagger2
public class Knife4jConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.zyxx"))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("SpringBoot项目 后台服务API接口文档")
        .description("使用 knife4j 搭建的后台服务API接口文档")
        .termsOfServiceUrl("http://localhost:8080/")
        .contact("lizhou")
        .version("1.0.0")
        .build();
  }
}

我们需要开放其静态资源的访问，启动类实现 WebMvcConfigurer 接口，重写 addResourceHandlers 方法

4、访问文档

启动项目，访问路径http://localhost:8080/doc.html

三、注意

访问时，如果提示 knife4j 文档异常，检查下自己的拦截器是否没有放开 knife4j 所需要的请求

需要在拦截器，放开请求

package com.zyxx.common.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.util.ArrayList;
import java.util.List;

/**
 * 注册拦截器
 *
 * @Author Lizhou
 **/
@Configuration
public class WebConfigurer implements WebMvcConfigurer {

  @Autowired
  private LoginInterceptor loginHandlerInterceptor;

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    InterceptorRegistration ir = registry.addInterceptor(loginHandlerInterceptor);
    // 拦截路径
    ir.addPathPatterns("/*");
    // 不拦截路径
    List<String> irs = new ArrayList<String>();
    irs.add("/login");
    irs.add("/api/*");
    // 开放knife4j
    irs.add("/doc.html");
    irs.add("/service-worker.js");
    irs.add("/swagger-resources");
    ir.excludePathPatterns(irs);
  }
}

四、使用

使用注解的方式与 swagger2 是一样的

1、controller

import com.zyxx.common.utils.ResponseResult;
import com.zyxx.sbm.service.MgtUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * <p>
 * 用户信息表 前端控制器
 * </p>
 *
 * @author lizhou
 * @since 2020-06-30
 */
@Api(tags = "后台管理端--用户模块")
@Controller
@RequestMapping("/mgt-user")
public class MgtUserController {

  @Autowired
  private MgtUserService mgtUserService;

  @ApiOperation(value = "分页查询用户数据", notes = "分页查询用户数据")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "page", value = "页码数", required = true),
      @ApiImplicitParam(name = "limit", value = "每页条数", required = true)
  })
  @GetMapping("list")
  @ResponseBody
  public ResponseResult listUser(int page, int limit) {
    return mgtUserService.listUser(page, limit);
  }
}

@Api，整个类的注释
@ApiOperation，方法上的注释
@ApiImplicitParams，参数列表的注释
@ApiImplicitParam，每一个参数的注释

2、实体类

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.extension.activerecord.Model;
import com.baomidou.mybatisplus.annotation.TableId;
import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.experimental.Accessors;

/**
 * <p>
 * 用户信息表
 * </p>
 *
 * @author lizhou
 * @since 2020-06-30
 */
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value="mgt_user对象", description="用户信息对象")
public class MgtUser extends Model<MgtUser> {

  private static final long serialVersionUID = 1L;

  @TableId(value = "id", type = IdType.AUTO)
  @ApiModelProperty(value = "主键ID")
  private Long id;

  @ApiModelProperty(value = "姓名")
  private String name;

  @ApiModelProperty(value = "年龄")
  private Integer age;

  @ApiModelProperty(value = "技能")
  private String skill;

  @ApiModelProperty(value = "评价")
  private String evaluate;

  @ApiModelProperty(value = "分数")
  private Long fraction;

  @Override
  protected Serializable pkVal() {
    return this.id;
  }
}

@ApiModel，实体类的注解
@ApiModelProperty，字段的注解

更多精彩内容其他人还在看