knife4j 系列注解及属性 和使用

knife4j 提供的常用注解及属性如下：

1. @Api：用于标记 Controller 类，并提供一些描述信息。

- tags：接口分组标签，用于在页面上展示。
- value：接口描述。
- description：详细描述接口的用途。
- produces：接口返回的数据类型，多个值用逗号隔开。
- consumes：接口接收的数据类型，多个值用逗号隔开。

示例代码：

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

2. @ApiOperation：用于标记接口并提供一些描述信息。

- value：接口描述。
- notes：详细描述接口的用途。
- httpMethod：请求方法类型，GET/POST/PUT/DELETE。
- response：接口返回的数据类型。
- responseContainer：接口返回数据类型的容器。

示例代码：

    @ApiOperation(value = "查询用户信息", notes = "根据用户ID查询用户信息")
    @GetMapping("/{userId}")
    public UserVO getUser(@PathVariable Long userId) {
        ...
    }

3. @ApiImplicitParam：用于描述单个请求参数的信息。

- name：参数名。
- value：参数描述。
- required：是否必填，默认为 false。
- dataType：参数类型。
- paramType：参数传递方式，query、header、path、body、form 中的一种。

示例代码：

    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "long", paramType = "path")
    @GetMapping("/{userId}")
    public UserVO getUser(@PathVariable Long userId) {
        ...
    }

4. @ApiImplicitParams：用于描述多个请求参数的信息。

- value：一个 @ApiImplicitParam 数组。

示例代码：

    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "query"),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "query")
    })
    @PostMapping("/login")
    public ResultVO login(String username, String password) {
        ...
    }

5. @ApiModel：用于描述数据模型的信息。

- value：模型名称。
- description：模型描述。

示例代码：

    @ApiModel(value = "用户信息", description = "用户基本信息")
    public class UserVO {
        ...
    }

6. @ApiModelProperty：用于描述数据模型的属性信息。

- value：属性描述。
- required：是否必填，默认为 false。
- dataType：属性类型。

示例代码：

    @ApiModel(value = "用户信息", description = "用户基本信息")
    public class UserVO {
        @ApiModelProperty(value = "用户ID", required = true, dataType = "long")
        private Long userId;

        @ApiModelProperty(value = "用户名", required = true, dataType = "string")
        private String username;

        ...
    }

使用示例：

1. 引入依赖：

    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.2</version>
    </dependency>

2. 在 Controller 类和接口方法上添加注解。

3. 启动项目，访问 http://localhost:port/doc.html 即可查看接口文档。