1. 简述

Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案。

直白来说，这是集成于java项目中的api管理工具。

2. 使用

引入jar包

创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，代码如下：


<properties>
    <java.version>1.8</java.version>
    <knife4j.version>3.0.3</knife4j.version>
</properties>

<!-- knife4j配置开始-->
<!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5项目-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>
<!-- knife4j配置结束-->

创建Swagger配置依赖

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                //描述字段支持Markdown语法
                .description("# 低代码 RESTful APIs")
                .termsOfServiceUrl("https://doc.superjson.com/")
                .contact("144@qq.com")
                .version("1.0")
                .build())
                //分组名称
                .groupName("用户服务")
                .select()
                //这里指定Controller扫描包路径
        		.apis(RequestHandlerSelectors.basePackage(" com.superjson.cloud.lowcode.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

接口Controller类

我们需要创建一个controller类来实现接口的展示，如下代码所示：

/**
 * @author 念兮为美
 * @datetime 2023/2/1 11:10
 * @desc 用来测试Knife4j的控制器
 */
@Api(tags = "测试模块")
@RestController
@RequestMapping("/test")
@Slf4j
@Validated
public class TestController {

  @Autowired private UserService userService;

  @ApiImplicitParams({
    @ApiImplicitParam(name = "keyword", value = "关键字，包括用户名名称，昵称，手机号等"),
  })
  @ApiResponses({
    @ApiResponse(code = 400, message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
  })
  @ApiOperation(value = "根据关键字查询用户信息")
  @GetMapping("/get")
  public RestMessage getUser(@RequestParam(value = "keyword") String keyword) {
    List<User> users = userService.queryByKeyword(keyword);
    return new RestMessage(users, 0, "success");
  }

  @ApiResponses({
    @ApiResponse(code = 400, message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
  })
  @ApiOperation(value = "保存用户信息")
  @PostMapping("/save")
  public RestMessage saveUser(
      @Validated @RequestBody UserDto userDto, BindingResult bindingResult) {
    BindingParamUtil.checkParam(bindingResult);
    return new RestMessage(userDto, 0, "success");
  }

  /**
   * @author 念兮为美
   * @datetime 2023/2/1 14:30
   * @desc 保存用户信息的dto
   */
  @AllArgsConstructor
  @NoArgsConstructor
  @Data
  @ApiModel(description = "保存用户请求信息")
  public class UserDto {

    @NotBlank(message = "用户名称不能为空")
    @ApiModelProperty(name = "username", value = "用户名称", required = true)
    private String username;

    @NotBlank(message = "用户昵称不能为空")
    @ApiModelProperty(name = "nickname", value = "用户昵称", required = true)
    private String nickname;
  }

  /**
   * @author 念兮为美
   * @datetime 2023/2/1 14:02
   * @desc 模拟返回信息
   */
  @ApiModel(description = "返回响应数据")
  @NoArgsConstructor
  @Data
  public class RestMessage {
    @ApiModelProperty(value = "是否成功")
    private boolean success = true;

    @ApiModelProperty(value = "返回对象")
    private Object data;

    @ApiModelProperty(value = "错误编号")
    private Integer code;

    @ApiModelProperty(value = "错误信息")
    private String message;

    public RestMessage(Object data, Integer code, String message) {
      this.data = data;
      this.code = code;
      this.message = message;
    }
  }
}

启动项目

启动Spring Boot项目，浏览器访问Knife4j的文档地址：http://localhost:8080/doc.html，即可查看效果。

【注意事项】 这里的端口号是你配置的端口号。

3. 注解解释

3.1 @Api

@Api：用在请求的类上，说明该类的作用

 tags="说明该类的作用"
 value="该参数没什么意义，所以不需要配置"

示例：

@Api(tags = "测试模块")

3.2 @ApiOperation

@ApiOperation：用在请求的方法上，说明方法的作用

value="说明方法的作用"
notes="方法的备注说明"

示例：

@ApiOperation(value = "保存用户信息")

3.3 @ApiImplicitParams

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

 @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
    name：参数名
    value：参数的汉字说明、解释
    required：参数是否必须传
    paramType：参数放在哪个地方
        · header --> 请求参数的获取：@RequestHeader
        · query --> 请求参数的获取：@RequestParam
        · path（用于restful接口）--> 请求参数的获取：@PathVariable
        · body（不常用）
        · form（不常用）    
    dataType：参数类型，默认String，其它值dataType="Integer"       
    defaultValue：参数的默认值

示例：

 @ApiImplicitParams({
    @ApiImplicitParam(name = "keyword", value = "关键字，包括用户名名称，昵称，手机号等"),
  })

3.4 @ApiResponses

@ApiResponses：用于请求的方法上，表示一组响应

 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类

示例：

@ApiResponses({
  @ApiResponse(code = 400, message = "请求参数没填好"),
  @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})

3.5 @ApiModel

@ApiModel：

用于响应类上，表示一个返回响应数据的信息，比如RestMessage类
或者用在post请求接口中，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候，比如UserDto类

@ApiModelProperty：用在属性上，描述响应类的属性

示例：

@AllArgsConstructor
 @NoArgsConstructor
 @Data
 @ApiModel(description = "保存用户请求信息")
 public class UserDto {

   @NotBlank(message = "用户名称不能为空")
    @ApiModelProperty(name = "username", value = "用户名称", required = true)
    private String username;

    @NotBlank(message = "用户昵称不能为空")
    @ApiModelProperty(name = "nickname", value = "用户昵称", required = true)
    private String nickname;
 }