【SpringBoot】廿二、SpringBoot中整合knife4j接口文檔

在項目開發中，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.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.spring.web.SpringfoxWebMvcConfiguration;

@SpringBootApplication
@ConditionalOnClass(SpringfoxWebMvcConfiguration.class)
public class SbmApplication implements WebMvcConfigurer {

    public static void main(String[] args) {
        SpringApplication.run(SbmApplication.class, args);
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

我們需要開放其靜態資源的訪問，啓動類實現 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，字段的註解

以上就是，SpringBoot中整合 knife4j 接口文檔的全部過程

如您在閱讀中發現不足，歡迎留言！！！