【SpringBoot】22、SpringBoot中整合knife4j接口文档

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

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

1、界面先赏

1.1、首页

1.2、接口文档

1.3、调试

2、整合 knife4j

2.1、引入 maven 依赖

<!-- knife4j接口文档 start -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version>
</dependency>

2.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 {@Beanpublic 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 所在的包

2.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.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);}@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

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

2.4、访问文档

启动项目，访问路径

http://localhost:8080/doc.html

3、注意

访问时，如果提示 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 {@Autowiredprivate LoginInterceptor loginHandlerInterceptor;@Overridepublic void addInterceptors(InterceptorRegistry registry) {InterceptorRegistration ir = registry.addInterceptor(loginHandlerInterceptor);// 拦截路径ir.addPathPatterns("/*");// 不拦截路径List<String> irs = new ArrayList<String>();irs.add("/login");irs.add("/api/*");// 开放knife4jirs.add("/doc.html");irs.add("/service-worker.js");irs.add("/swagger-resources");ir.excludePathPatterns(irs);}
}

4、使用

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

4.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 {@Autowiredprivate MgtUserService mgtUserService;@ApiOperation(value = "分页查询用户数据", notes = "分页查询用户数据")@ApiImplicitParams({@ApiImplicitParam(name = "page", value = "页码数", required = true),@ApiImplicitParam(name = "limit", value = "每页条数", required = true)})@GetMapping("list")@ResponseBodypublic ResponseResult listUser(int page, int limit) {return mgtUserService.listUser(page, limit);}
}

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

4.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;@Overrideprotected Serializable pkVal() {return this.id;}
}

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

5、分组展示

我们针对多个包内的 API 接口，可以选择分组展示，配置如下：

package com.asurplus.common.knife4j;import com.asurplus.common.consts.SystemConst;
import org.springframework.beans.factory.annotation.Value;
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;/*** swagger2 配置** @Author Lizhou*/
@Configuration
@EnableSwagger2
public class Knife4jConfig {@Bean("appApi")public Docket appApi() {return new Docket(DocumentationType.SWAGGER_2)// 分组名称.groupName("APP端API文档").apiInfo(apiInfo()).select()// 扫描包位置，扫描所有带有此注解的方法.apis(RequestHandlerSelectors.basePackage("com.asurplus.api")).paths(PathSelectors.any()).build();}@Bean("adminApi")public Docket adminApi() {return new Docket(DocumentationType.SWAGGER_2)// 分组名称.groupName("管理端API文档").apiInfo(apiInfo()).select()// 扫描包位置，扫描所有带有此注解的方法.apis(RequestHandlerSelectors.basePackage("com.asurplus.system")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder()// 标题.title(SystemConst.SYSTEM_ITEM_NAME + "管理后台服务API接口文档")// 简介.description("使用 knife4j 搭建的后台服务API在线接口文档")// 服务条款url.termsOfServiceUrl("无")// 版本.version("1.0.0")// 作者.contact(new Contact("Administrators", "无", "无"))// 构建.build();}
}

6、开启认证功能

knife4j 新的版本中推出了生产环境保护与认证功能，只需要在配置文件中设置即可：

# swagger配置
knife4j:# 开启增强模式enable: true# 开启生产环境保护production: false# 开启认证功能basic:enable: trueusername: adminpassword: 123456

在生产环境中，我们需要开启生产环境保护，以防接口信息泄露，造成安全生产问题

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

如您在阅读中发现不足，欢迎留言！！！