SpringBoot4.0整合knife4j 在线文档完整使用

作为一名后台开发人员，在前后端分离项目的开发过程中，我们写好了后台接口之后总免不了要给前端同事提供一份详细的API接口文档，写完一个接口又要补充一个接口的文档，过程还挺繁琐的。那么有没有一款工具让我们不用再些这些繁琐的API文档呢？答案是有的。之前我们在项目中配置swagger结合相关的注解来生成API文档界面，只是界面不是那么美观，还必须在每个接口控制器方法中添加很多的注解，代码侵入性比较强。

现在越来越多的开发人员使用Knif4j来生成API文档，它是升级版的swagger, 不仅具有美观的界面，而且不需要在控制器方法中添加非常多的参数注解。哪怕不加任何注解，只要在项目中集成并配置好Docket类bean，就能生成界面美观的API接口文档，而且还有接口调试功能。

小白零基础全栈课程项目企业级实战

1. 直接文档看效果

小白零基础全栈课程项目企业级实战

2. 项目依赖

小白零基础全栈课程项目企业级实战

    4.0.0

    com.cloud.xx
    xx-cloud
    1.0-SNAPSHOT

    
        17
        17
        3.4.3
        8.0.16
        5.8.18
    


    
        org.springframework.boot
        spring-boot-starter-parent
        4.0.1-SNAPSHOT
    

    

        
            org.springframework.boot
            spring-boot-starter-web
        

           
        
            com.github.xiaoymin
            knife4j-openapi3-jakarta-spring-boot-starter
            4.5.0
        

        
            org.apache.commons
            commons-lang3
        

        
            org.springframework.boot
            spring-boot-configuration-processor
            true
        

        
            org.springframework.boot
            spring-boot-starter
        

        
            javax.servlet
            javax.servlet-api
            3.1.0
            provided
        

        
            org.springframework.boot
            spring-boot-starter-validation
        

        
            com.dtflys.forest
            forest-spring-boot3-starter
            1.5.35
        

        
            cn.hutool
            hutool-all
            ${hutool-all.version}
        
        
            com.baomidou
            mybatis-plus-spring-boot4-starter
            3.5.14
        

        
            mysql
            mysql-connector-java
            ${mysql.connector.version}
        
        
            com.alibaba
            fastjson
            1.2.79
        
        
            org.projectlombok
            lombok
            1.18.22
        
        
            org.springframework.boot
            spring-boot-starter-actuator
        

        
        
            org.postgresql
            postgresql
            42.7.8
        

    

    
        cloud-boot-jiabo
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                
                    true
                
            
        

    

    
        
            spring-snapshots
            https://repo.spring.io/snapshot
            true
        
        
            spring-milestones
            https://repo.spring.io/milestone
        
    
    
        
            spring-snapshots
            https://repo.spring.io/snapshot
        
        
            spring-milestones
            https://repo.spring.io/milestone
        
    

3. 实体类配置

小白零基础全栈课程项目企业级实战

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 = "测试问好")

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]，序列化正常
  }

}

小白零基础全栈课程项目企业级实战