当前位置：首页 > article >正文

在Swagger（现称为OpenAPI）中各类@api之间的区别

article 2025/1/5 13:47:35

在Swagger（现称为OpenAPI）中，@ApiOperation 是用来描述单个API操作的注解。除此之外，Swagger还提供了其他一些类似的注解，它们用于不同层次或目的来增强API文档的详细程度和可读性。以下是这些注解及其之间的区别：

1. `@Api`

用途：描述整个控制器类的功能。
位置：应用于控制器类上。
属性：
- tags：为该控制器定义标签，方便分类管理。
- description：提供对该控制器的简短描述。
- value：与tags类似，但通常作为主要标签使用。

示例

@Api(tags = "用户管理接口", description = "包含所有用户相关的API操作")
@RestController
@RequestMapping("/api/users")
public class UserController {
    // ...
}

2. `@ApiOperation`

用途：描述一个具体的API操作（即一个HTTP请求处理方法）。
位置：应用于控制器中的方法上。
属性：
- value：API操作的简短标题或摘要。
- notes：API操作的详细说明或备注信息。
- response：指定响应的数据类型。
- httpMethod：指定HTTP方法（GET、POST等），通常从方法上的HTTP注解推断出来。
- tags：为该API操作定义标签，可以是多个。

示例

@ApiOperation(value = "获取用户列表", notes = "返回所有用户的列表")
@GetMapping("/list")
public List<User> getUsers() {
    // ...
}

3. `@ApiParam`

用途：描述方法参数的信息，特别是那些不在方法签名中显式声明的参数，如查询参数、路径变量、请求头等。
位置：应用于方法参数上。
属性：
- value：参数的描述。
- name：参数名。
- required：是否必需。
- defaultValue：默认值。
- allowableValues：允许的值范围。

示例

@ApiOperation(value = "根据ID获取用户详情")
@GetMapping("/{id}")
public User getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    // ...
}

4. `@ApiResponse` 和 `@ApiResponses`

用途：描述API操作可能产生的响应信息，包括状态码、消息、响应体的数据类型等。
位置：应用于方法上，通常与@ApiOperation一起使用。
属性：
- code：HTTP状态码。
- message：对响应的简短描述。
- response：响应的数据类型。
- responseContainer：当返回集合时，指定容器类型（如List, Set等）。

示例

@ApiOperation(value = "创建新用户")
@ApiResponses({
    @ApiResponse(code = 201, message = "用户创建成功", response = User.class),
    @ApiResponse(code = 400, message = "无效的输入数据"),
    @ApiResponse(code = 500, message = "服务器内部错误")
})
@PostMapping
public ResponseEntity<User> createUser(@RequestBody User user) {
    // ...
}

5. `@ApiImplicitParam` 和 `@ApiImplicitParams`

用途：用于描述API操作的隐式参数信息，特别是那些不直接出现在方法签名中的参数，如查询参数、表单参数、请求头等。
位置：应用于方法上，通常与@ApiOperation一起使用。
属性：
- name：参数名。
- value：参数的描述。
- required：是否必需。
- paramType：参数类型（如query, header, path等）。
- dataType：参数的数据类型。

示例

@ApiOperation(value = "搜索用户")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", dataType = "String"),
    @ApiImplicitParam(name = "age", value = "用户年龄", paramType = "query", dataType = "Integer")
})
@GetMapping("/search")
public List<User> searchUsers(@RequestParam(required = false) String name,
                              @RequestParam(required = false) Integer age) {
    // ...
}