knife4j常用注解

通过 knife4j就可以生成接口文档，那么我们就不需要 Yapi 了？

1、Yapi 是设计阶段使用的工具，管理和维护接口

2、Swagger 在开发阶段使用的框架，帮助后端开发人员做后端的接口测试

1. @Api

1.1 作用

用于类上，标注该类是一个 API 接口类，并给出简要说明。

1.2 示例

@Api(tags = "员工管理接口", description = "提供员工的增删改查接口")
@RestController
@RequestMapping("/api/employee")
public class EmployeeController {
    // 控制器中的API接口
}

1.3 说明

• tags 用于标记模块名或者功能组名。
• description 用于描述该模块的详细功能。

2. @ApiOperation

2.1 作用

用在方法上，例如Controller的方法，说明方法的用途、作用

2.2 示例

@ApiOperation(value = "根据ID获取员工信息", notes = "通过员工ID获取详细的员工信息")
@GetMapping("/employee/{id}")
public Employee getEmployeeById(@PathVariable Long id) {
    // 业务逻辑
    return employeeService.getEmployeeById(id);
}

2.3 说明

• value 参数描述接口的主要功能。
• notes 参数提供更多详细信息。

3. @ApiParam

3.1 作用

用于描述方法中的参数信息。

3.2 示例

@ApiOperation(value = "创建新员工")
@PostMapping("/employee")
public Employee createEmployee(@ApiParam(value = "员工信息") @RequestBody Employee employee) {
    // 业务逻辑
    return employeeService.createEmployee(employee);
}

3.3 说明

• value 参数用于描述具体参数的功能和作用。

4. @ApiModel

4.1 作用

用于描述一个实体对象，也就是请求和响应中的模型。

4.2 示例

@ApiModel(description = "员工实体类")
public class Employee {
    
    @ApiModelProperty(value = "员工ID", example = "1001")
    private Long id;

    @ApiModelProperty(value = "员工姓名", example = "张三")
    private String name;

    @ApiModelProperty(value = "员工年龄", example = "30")
    private Integer age;
    
    // Getters and Setters
}

5. @ApiModelProperty

5.1 作用

用于描述模型属性的详细信息，通常配合 @ApiModel 使用。

5.2 示例

@ApiModel(description = "员工实体类")
public class Employee {

    @ApiModelProperty(value = "员工ID", example = "1001", required = true)
    private Long id;

    @ApiModelProperty(value = "员工姓名", example = "张三")
    private String name;

    @ApiModelProperty(value = "员工年龄", example = "30")
    private Integer age;
    
    // Getters and Setters
}

5.3 说明

• value 描述属性的功能。
• example 给出具体示例。
• required 表示该字段是否必须。

6. 总结

说明：

1. @ApiOperation：用于描述接口的主要功能和说明，常用于方法上。
2. @Api：用于类上，标识该类是一个 API 模块，并可以描述模块的功能。
3. @ApiParam：用于方法参数上，描述参数的含义和作用，便于理解。
4. @ApiModel 和 @ApiModelProperty：配合使用来描述实体类（模型）的详细信息，特别是用于复杂对象（如请求体、响应体）的参数描述。
5. @ApiImplicitParams 和 @ApiImplicitParam：用于简化 URL 查询参数或表单参数的定义，适合 @RequestParam 或 @PathVariable 之类的参数。
6. @ApiResponses 和 @ApiResponse：描述接口的多种可能响应，特别是在接口有不同状态码返回时。
7. @ApiIgnore：用于隐藏某些不需要出现在文档中的接口或参数。
8. @ApiResponseObject：描述接口的返回类型，指明返回对象。