一个好的项目，接口文档是非常重要的，除了能帮助前端和后端开发人员更快地协作完成开发任务，接口文档还能用来生成资源权限，对权限访问控制的实现有很大的帮助。
这篇文章介绍一下企业中常用的接口文档工具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 = "heyl163_com@163.com";
private static final String version = "1.0.0";
private final OpenApiExtensionResolver openApiExtensionResolver;
@Autowired
public Knife4jConfig(OpenApiExtensionResolver openApiExtensionResolver) {
this.openApiExtensionResolver = openApiExtensionResolver;
}
@Bean
public 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
