作为一名后台开发人员，在前后端分离项目的开发过程中，我们写好了后台接口之后总免不了要给前端同事提供一份详细的API接口文档，写完一个接口又要补充一个接口的文档，过程还挺繁琐的。那么有没有一款工具让我们不用再些这些繁琐的API文档呢？答案是有的。之前我们在项目中配置swagger结合相关的注解来生成API文档界面，只是界面不是那么美观，还必须在每个接口控制器方法中添加很多的注解，代码侵入性比较强。
现在越来越多的开发人员使用Knif4j来生成API文档，它是升级版的swagger,不仅具有美观的界面，而且不需要在控制器方法中添加非常多的参数注解。哪怕不加任何注解，只要在项目中集成并配置好Docket类bean，就能生成界面美观的API接口文档，而且还有接口调试功能。
1. 直接文档看效果
2. 项目依赖
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>
<groupId>com.cloud.xx</groupId>
<artifactId>xx-cloud</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<mybatis-plus.version>3.4.3</mybatis-plus.version>
<mysql.connector.version>8.0.16</mysql.connector.version>
<hutool-all.version>5.8.18</hutool-all.version>
</properties>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.1-SNAPSHOT</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--knife4j 在线接口文档-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>com.dtflys.forest</groupId>
<artifactId>forest-spring-boot3-starter</artifactId>
<version>1.5.35</version>
</dependency>
<dependency>
<groupId>cn.hutool</groupId>
<artifactId>hutool-all</artifactId>
<version>${hutool-all.version}</version>
</dependency>
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-spring-boot4-starter</artifactId>
<version>3.5.14</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>${mysql.connector.version}</version>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.79</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.22</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- 或者使用PostgreSQL兼容驱动 -->
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>42.7.8</version>
</dependency>
</dependencies>
<build>
<finalName>cloud-boot-jiabo</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<includeSystemScope>true</includeSystemScope>
</configuration>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>spring-snapshots</id>
<url>https://repo.spring.io/snapshot</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
<id>spring-milestones</id>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>https://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>https://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
</project>3. 实体类配置
java
package com.cloud.xx.entity
import com.baomidou.mybatisplus.annotation.{IdType, TableField, TableId, TableName}
import com.baomidou.mybatisplus.extension.activerecord.Model
import io.swagger.v3.oas.annotations.media.Schema
import lombok.ToString
import scala.beans.BeanProperty
@TableName(value = "user", schema = "ets")
class UserEntity extends Model[UserEntity] {
@Schema(description = "主键")
@BeanProperty
@TableId(value = "id", `type` = IdType.ASSIGN_ID)
var id: String = _
@Schema(description = "账号昵称")
@BeanProperty
var userName : String = _
@Schema(description = "创建时间")
@BeanProperty
var createTime : String = _
@Schema(description = "更新时间")
@BeanProperty
var updateTime : String = _
@Schema(description = "状态")
@BeanProperty
var appState : String = _
override def toString: String =
s"UserEntity(id=$id, userName=$userName, createTime=$createTime, updateTime=$updateTime, appState=$appState)"
}
4. Controller 配置
1. 类上面配置分组
description写备注简介作用针对这个接口
name 接口名称
@Tag(name = "用户信息", description = "用户相关接口")
2. 方法上配置说明
description 写备注简介作用针对这个接口
summary 接口名称
@Operation(summary = "测试问好", description = "测试问好")
java
package com.cloud.xx.controller
import com.cloud.xx.common.utils.R
import com.cloud.xx.mapper.UserMapper
import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.tags.Tag
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.web.bind.annotation.{GetMapping, RequestMapping, RequestParam, RestController}
import scala.collection.convert.ImplicitConversions.`collection AsScalaIterable`
@Tag(name = "用户信息", description = "用户相关接口")
@RestController
@RequestMapping(Array("/user"))
class UserController {
@Autowired
val etsEntityService: UserMapper = null
/**
* 测试Vabase海量数据库FT项目对接
*
* @param id
* @return
*/
@Operation(summary = "测试问好", description = "测试问好")
@GetMapping(Array("getInfo")) def ok(@RequestParam("id") id: String): R[_] = {
import scala.jdk.CollectionConverters._
val entity = etsEntityService.selectList(null)
val list = entity.map { num =>
num.setUserName(num.getUserName + "1")
num
}
R.ok(list.asJava) // 现在是 List[UserEntity]，序列化正常
}
}
