后台管理系统的通用权限解决方案(三)SpringBoot整合Knife4j生成接口文档

1 Knife4j介绍

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

其底层是对Springfox的封装，使用方式也和Springfox一致，只是对接口文档UI进行了优化。其核心功能包括文档说明和在线调试。

2 Knife4j案例

• 1）创建maven工程``，并配置其pom.xml文件如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.2.2.RELEASE</version><relativePath/></parent><groupId>com.hsgx</groupId><artifactId>knife4j-demo</artifactId><version>1.0-SNAPSHOT</version><properties><maven.compiler.source>8</maven.compiler.source><maven.compiler.target>8</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency><!--knife4j--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.1</version></dependency></dependencies>
</project>

• 2）创建实体类User和控制器UserController类，跟Springfox的写法是一样的

package com.hsgx.pojo;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(description = "用户实体")
public class User {@ApiModelProperty(value = "主键")private Integer id;@ApiModelProperty(value = "姓名")private String name;@ApiModelProperty(value = "年龄")private Integer age;@ApiModelProperty(value = "地址")private String address;
}

package com.hsgx.controller;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/user")
@Api(tags = "用户控制器")
public class UserController {@ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "页码",required = true, type = "Integer"),@ApiImplicitParam(name = "pageSize", value = "每页条数",required = true, type = "Integer"),})@ApiOperation(value = "分页查询用户信息")@GetMapping(value = "page/{pageNum}/{pageSize}")public String findByPage(@PathVariable Integer pageNum,@PathVariable Integer pageSize) {return "OK";}
}

• 3）创建配置属性类SwaggerProperties，映射配置文件的配置信息

package com.hsgx.config;import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;@Data
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {private Map<String, DocketInfo> docket = new LinkedHashMap<>(); //分组文档@Datapublic static class DocketInfo {private String title = ""; //标题private String group = ""; //组名private String description = ""; //描述private String version = ""; //版本private String name = ""; // 联系人private String url = ""; // 联系人urlprivate String email = ""; // 联系人emailprivate String basePackage = ""; //swagger会解析的包路径private List<String> basePath = new ArrayList<>(); //swagger会解析的url规则private List<String> excludePath = new ArrayList<>(); //在basePath基础上需要排除的url// 如果没有填写组名，则直接用标题作为组名public String getGroup() {if (group == null || group.isEmpty()) {return title;}return group;}}
}

• 4）创建自动配置类SwaggerAutoConfiguration

package com.hsgx.config;import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.beans.factory.BeanFactoryAware;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
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;import java.util.ArrayList;
import java.util.LinkedList;
import java.util.List;@Configuration
@ConditionalOnProperty(name = "swagger.enabled", havingValue = "true", matchIfMissing = true)
@EnableSwagger2
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerAutoConfiguration implements BeanFactoryAware {@Autowiredprivate SwaggerProperties swaggerProperties;@Autowiredprivate BeanFactory beanFactory;@Bean@ConditionalOnMissingBeanpublic List<Docket> createRestApi(){ConfigurableBeanFactory configurableBeanFactory = (ConfigurableBeanFactory) beanFactory;List<Docket> docketList = new LinkedList<>();// 分组创建for (String groupName : swaggerProperties.getDocket().keySet()){SwaggerProperties.DocketInfo docketInfo = swaggerProperties.getDocket().get(groupName);ApiInfo apiInfo = new ApiInfoBuilder()// 页面标题.title(docketInfo.getTitle())// 创建人.contact(new Contact(docketInfo.getName(),docketInfo.getUrl(),docketInfo.getEmail()))// 版本号.version(docketInfo.getVersion())// 描述.description(docketInfo.getDescription()).build();// base-path处理，当没有配置任何path的时候，解析/**if (docketInfo.getBasePath().isEmpty()) {docketInfo.getBasePath().add("/**");}List<Predicate<String>> basePath = new ArrayList<>();for (String path : docketInfo.getBasePath()) {basePath.add(PathSelectors.ant(path));}// exclude-path处理List<Predicate<String>> excludePath = new ArrayList<>();for (String path : docketInfo.getExcludePath()) {excludePath.add(PathSelectors.ant(path));}Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).groupName(docketInfo.getGroup()).select()// 为当前包路径.apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage())).paths(Predicates.and(Predicates.not(Predicates.or(excludePath)),Predicates.or(basePath))).build();configurableBeanFactory.registerSingleton(groupName, docket);docketList.add(docket);}return docketList;}@Overridepublic void setBeanFactory(BeanFactory beanFactory) throws BeansException {this.beanFactory = beanFactory;}
}

• 5）创建配置文件application.yml

server:port: 8082
swagger:enabled: true #是否启用swaggerdocket:user:title: 用户模块group: userdescription: 用户模块version: 1.0name: hsgxurl:email:base-package: com.hsgx.controllerorder:title: 订单模块group:description: 订单模块version: 1.0name: hsgxurl:email:base-package: com.hsgx.controller

• 6）创建启动类Knife4jDemoApp

package com.hsgx;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplication
public class Knife4jDemoApp {public static void main(String[] args) {SpringApplication.run(Knife4jDemoApp.class, args);}
}

• 6）启动服务，访问地址：http://localhost:8082/doc.html

由结果可知，Knif34j生成的文档包含两个组，和我们在配置文件中配置的一样。

…

本节完，更多内容查阅：后台管理系统的通用权限解决方案

延伸阅读：后台管理系统的通用权限解决方案(二)SpringBoot整合Swagger Springfox实现接口日志文档