SpringBoot整合Knife4j接口文档生成工具

一个好的项目，接口文档是非常重要的，除了能帮助前端和后端开发人员更快地协作完成开发任务，接口文档还能用来生成资源权限，对权限访问控制的实现有很大的帮助。

这篇文章介绍一下企业中常用的接口文档工具Knife4j（基于Swagger实现）的使用。

SpringBoot整合Knife4j的步骤

创建项目

首先，通过Intellij IDEA创建一个springboot项目，命名为springboot-knife4j

修改配置

修改pom.xml

修改一下springboot的版本和java的版本（本篇文章使用springboot 2.5.9版本），然后添加knife4j的依赖。

完整的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 https://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.5.9</version><relativePath /></parent><groupId>cn.edu.sgu.www</groupId><artifactId>springboot-knife4j</artifactId><version>0.0.1-SNAPSHOT</version><properties><java.version>1.8</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><!--knife4j--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version></dependency><!--lombok--><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.22</version><optional>true</optional></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
</project>

修改application.yml

开启knife4j的增强模式

knife4j:enable: true

创建Knife4j配置类

package cn.edu.sgu.www.knife4j.config;import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
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.EnableSwagger2WebMvc;/*** Knife4j配置类* @author heyunlin* @version 1.0*/
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {// 指定Controller包路径（必须）private static final String basePackage = "cn.edu.sgu.www.knife4j.controller";private static final String host = "LAPTOP-0N6P8HTP";private static final String title = "Spring Boot整合Knife4j案例项目";private static final String description = title + "在线API文档";private static final String termsOfServiceUrl = "https://www.apache.org/licenses/LICENSE-2.0";private static final String contactName = "heyunlin"; // 联系人private static final String contactUrl = "https://gitee.com/he-yunlin";private static final String contactEmail = "[e-mail]";private static final String version = "1.0.0";private final OpenApiExtensionResolver openApiExtensionResolver;@Autowiredpublic Knife4jConfig(OpenApiExtensionResolver openApiExtensionResolver) {this.openApiExtensionResolver = openApiExtensionResolver;}@Beanpublic Docket docket() {String groupName = "1.0.0";return new Docket(DocumentationType.SWAGGER_2).host(host).apiInfo(apiInfo()).groupName(groupName).select().apis(RequestHandlerSelectors.basePackage(basePackage)).paths(PathSelectors.any()).build().extensions(openApiExtensionResolver.buildExtensions(groupName));}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(title).description(description).termsOfServiceUrl(termsOfServiceUrl).contact(new Contact(contactName, contactUrl, contactEmail)).version(version).build();}}

创建控制器类

新建UserController，类上使用@Api注解，在方法上使用@ApiOpration注解

package cn.edu.sgu.www.knife4j.controller;import cn.edu.sgu.www.knife4j.dto.UserLoginDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author heyunlin* @version 1.0*/
@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {@ApiOperation("登录认证")@PostMapping("login")public String login(UserLoginDTO userLoginDTO) {return "登录成功";}}

创建传输对象实体类

package cn.edu.sgu.www.knife4j.dto;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;/*** @author heyunlin* @version 1.0*/
@Data
@ApiModel
public class UserLoginDTO {@ApiModelProperty(value = "用户名", required = true)private String username;@ApiModelProperty(value = "密码", required = true)private String password;
}

除此之外，Knife4j还提供了使用在参数上的注解，如：@ApiParam

package cn.edu.sgu.www.knife4j.controller;import cn.edu.sgu.www.knife4j.dto.UserLoginDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author heyunlin* @version 1.0*/
@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {@ApiOperation("登录认证")@PostMapping("/login")public String login(UserLoginDTO userLoginDTO) {return "登录成功~";}@ApiOperation("用户注册")@PostMapping("/register")public String register(@ApiParam(value = "用户名",  required = true) String username,@ApiParam(value = "密码",  required = true) String password) {return "注册成功~";}}

最后，启动项目，访问localhost:端口号/doc.html

 

好了，文章就分享到这里了，代码已经上传到gitee，可按需获取~

Spring Boot整合Knife4j案例项目https://gitee.com/he-yunlin/springboot-knife4j.git