文章目录

  • 1. 简述
  • 2. 使用
  • 3. 注解解释
    • 3.1 @Api
    • 3.2 @ApiOperation
    • 3.3 @ApiImplicitParams
    • 3.4 @ApiResponses
    • 3.5 @ApiModel

1. 简述

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

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

2. 使用

  1. 引入jar包

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

<properties><java.version>1.8</java.version><knife4j.version>3.0.3</knife4j.version></properties><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency>
  1. 创建Swagger配置依赖
@Configuration@EnableSwagger2WebMvcpublic 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;}}
  1. 接口Controller类

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

/** * @author 念兮为美 * @datetime 2023/2/1 11:10 * @desc 用来测试Knife4j的控制器 */@Api(tags = "测试模块")@RestController@RequestMapping("/test")@Slf4j@Validatedpublic 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@Datapublic 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;}}}
  1. 启动项目

启动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：数字，例如400message：信息，例如"请求参数没填好"response：抛出异常的类

示例：

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

3.5 @ApiModel

@ApiModel：

  1. 用于响应类上，表示一个返回响应数据的信息，比如RestMessage类

  2. 或者用在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; }