Spring Boot集成Knife4j文档工具

Knife4j 搭建

Knife4j环境的的搭建和Swagger一样都比较简单，只需要极简的配置即可。

maven依赖

我使用的是较高版本的基于openapi规范的依赖包，OpenAPI2(Swagger)规范是Knife4j之前一直提供支持的版本，底层依赖框架为Springfox。

此次在4.0版本开始Knife4j有了新的变化，主要有以下几点：

• Springfox版本选择的依然是2.10.5版本，而并非springfox最新3.0.0版本

• 不支持以Springfox框架为基础的OpenAPI3规范,放弃Springfox项目的后续版本适配支持工作

• Spring Boot 版本建议 2.4.0~3.0.0之间

  <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>2.7.6</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi2-spring-boot-starter</artifactId> <version>4.3.0</version> </dependency>

创建接口

我们创建两个控制器controller类，并创建几个API方法加上@Api、@ApiOperation、@ApiParam注解，更多的注解使用可以参考Sprinboot 集成 Swagger3.0 详解。

BuyController类

import com.springboot101.po.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;


@RequestMapping("/buy")
@Api(tags = "商家管理")
@RestController
public class BuyController {


    @ApiOperation("创建商家")
    @PostMapping("/createBuy")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        return ResponseEntity.ok(user);
    }


    @ApiOperation("更新商家")
    @PostMapping("/updateBuy/{id}")
    public ResponseEntity<User> updateUser(@ApiParam(value = "商家主键ID", required = true) @PathVariable("id") String id,
                                           @RequestHeader("token") String token,
                                           @RequestParam("name") String name,
                                           @RequestBody User user) {
        return ResponseEntity.ok(user);
    }
}

UserController类

import com.springboot101.po.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;


@RequestMapping("/user")
@Api(tags = "用户管理")
@RestController
public class UserController {


    @ApiOperation("创建用户")
    @PostMapping("/createUser")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        return ResponseEntity.ok(user);
    }


    @ApiOperation("更新用户")
    @PostMapping("/updateUser/{id}")
    public ResponseEntity<User> updateUser(@ApiParam(value = "用户主键ID", required = true) @PathVariable("id") String id,
                                           @RequestHeader("token") String token,
                                           @RequestParam("name") String name,
                                           @RequestBody User user) {
        return ResponseEntity.ok(user);
    }
}

Knife4j配置

在以前的版本中，开发者需要在配置类中手动使用@EnableKnife4j注解来使用增强功能，自2.0.6版本后，只需要在配置文件中配置knife4j.enable=true即可，不在使用注解开启了。

@Configuration
@EnableKnife4j 
public class Knife4jConfig {


}

而且自2.0.6版本开始，将UI界面中一些个性化配置从代码中剥离，我们可以直接在application.yml文件中配置文档属性，使用起来更加的简洁了。

# Knife4j配置
knife4j:
  # 开启增强配置
  enable: true
  #开启Basic登录认证功能
  openapi:
    title: xx官方文档
    description: ""
    email: [email protected]
    concat: xx
    url: http://xiaofucode.com
    version: v1.0 # 版本号
    license: Apache 2.0
    license-url: https://fire100.top
    terms-of-service-url: https://fire100.top #API服务条款

默认情况下，如果不设置API的分组，Knife4j会扫描全部标注了@Api、@ApiOperation等注解类，将它们全部放入到default分组。

图片

API分组

knife4j的分组支持我们在yml文件中配置，开启knife4j.openapi.group。

例如：新建user、buy模块就代表了不同的分组，其中的子项：

• group-name：分组的名称；

• api-rule：组内资源扫描策略，目前支持根据package类路径扫描，annotation扫描特定注解；

• api-rule-resources：资源路径（数组），策略为 package 时填写完整的controller类路径，策略为 annotation 时填写特定注解的完整路径；

  Knife4j配置

  knife4j:
  # 开启增强配置
  enable: true
  #开启Basic登录认证功能
  openapi:
  title: xx
  description: "xx"
  email: [email protected]
  concat: xx
  url: http://xiaofucode.com
  version: v1.0 # 版本号
  license: Apache 2.0
  license-url: https://fire100.top
  terms-of-service-url: https://fire100.top #API服务条款
  # API分组配置
  group:
  user:
  group-name: 用户管理 # 组名
  api-rule: package # 扫描规则，是根据包路径还是请求路径
  api-rule-resources: # 扫描的资源
  - com.springboot101.controller.user
  buy:
  group-name: 商家管理
  api-rule: package
  api-rule-resources:
  - com.springboot101.controller.buy
  #user:

  group-name: 用户管理

  api-rule: annotation

  api-rule-resources:

  - io.swagger.annotations.Api # 扫描带有 @Api 注解的接口

  buy:

  group-name: 商家管理

  api-rule: annotation

  api-rule-resources:

  - io.swagger.annotations.Api # 扫描带有 @Api 注解的接口

用户认证

knife4j内置了Basic认证，只要在开启basic下配置认证用户名和密码即可。

knife4j:
  #开启Basic登录认证功能
  basic:
    enable: true
    # Basic认证用户名
    username: admin
    # Basic认证密码
    password: 123456

再次访问文档路径时会弹出登录框。

图片

完整的knife4j配置

以下是knife4j的完整配置：

server:
  port: 9002


# Knife4j配置
knife4j:
  # 开启增强配置
  enable: true
  #开启Basic登录认证功能
  basic:
    enable: true
    # Basic认证用户名
    username: admin
    # Basic认证密码
    password: 123456
  openapi:
    title: xxx
    description: "xx"
    email: [email protected]
    concat: xx
    url: http://xiaofucode.com
    version: v1.0 # 版本号
    license: Apache 2.0
    license-url: https://fire100.top
    terms-of-service-url: https://fire100.top #API服务条款
    # API分组配置
    group:
      user:
        group-name: 用户管理 # 组名
        api-rule: package # 扫描规则，是根据包路径还是请求路径
        api-rule-resources: # 扫描的资源
          - com.springboot101.controller.user
      buy:
        group-name: 商家管理
        api-rule: package
        api-rule-resources:
          - com.springboot101.controller.buy
      #user:
#        group-name: 用户管理
#        api-rule: annotation
#        api-rule-resources:
#          - io.swagger.annotations.Api   # 扫描带有 @Api 注解的接口
#      buy:
#        group-name: 商家管理
#        api-rule: annotation
#        api-rule-resources:
#          - io.swagger.annotations.Api   # 扫描带有 @Api 注解的接口