Swagger 3 注解使用指南

1. 基本信息注解

@OpenAPIDefinition

• 描述：用于定义整个 API 文档的基本信息。
• 可用于：类、接口。
• 属性：
  • info：指定 @Info 注解的对象，用于描述 API 文档的基本信息。

@Info

• 描述：用于定义 API 文档的基本信息。
• 可用于：类、接口。
• 属性：
  • title：API 的标题。
  • description：API 的描述。
  • version：API 的版本号。
  • termsOfService：服务条款的 URL。
  • contact：指定 @Contact 注解的对象，用于描述联系人信息。
  • license：指定 @License 注解的对象，用于描述许可证信息。

@Contact

• 描述：用于定义 API 文档中的联系人信息。
• 可用于：类、接口。
• 属性：
  • name：联系人的名称。
  • url：联系人的网址。
  • email：联系人的电子邮件地址。

@License

• 描述：用于定义 API 文档中的许可证信息。
• 可用于：类、接口。
• 属性：
  • name：许可证的名称。
  • url：许可证的网址。

2. 分组注解

@Tag

• 描述：用于给 API 分组，用途类似于为 API 文档添加标签。
• 可用于：方法、类、接口。
• 属性：
  • name：分组的名称。

3. 请求方法注解

以下注解用于描述 API 的请求方法：

@Operation

• 描述：用于描述 API 的操作。
• 可用于：方法。
• 属性：
  • summary：操作的摘要信息。
  • description：操作的详细描述。
  • tags：指定 @Tag 注解的对象数组，用于将操作归类到特定的分组。
  • parameters：指定 @Parameter 注解的对象数组，用于描述操作的输入参数。
  • responses：指定 @ApiResponse 注解的对象数组，用于描述操作的响应结果。
  • requestBody：指定 @RequestBody 注解的对象，用于描述操作的请求体。

@Parameter

• 描述：用于描述操作的输入参数。

• 可用于：方法。

• 属性：

  • name：参数的名称。
  • in：参数的位置，可以是 path、query、header、cookie 中的一种。
  • description：参数的描述。
  • required：参数是否必需，默认为 false。

• schema：指定 @Schema 注解的对象，用于描述参数的数据类型。

@RequestBody

• 描述：用于描述操作的请求体。
• 可用于：方法。
• 属性：
  • required：请求体是否必需，默认为 false。
  • content：指定 @Content 注解的对象数组，用于描述请求体的内容。

@ApiResponse

• 描述：用于描述操作的响应结果。
• 可用于：方法。
• 属性：
  • responseCode：响应的状态码。
  • description：响应的描述。
  • content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

• 描述：用于描述请求体或响应的内容。
• 可用于：方法。
• 属性：
  • mediaType：内容的媒体类型。
  • schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

• 描述：用于描述数据模型的属性。
• 可用于：方法、类、接口。
• 属性：
  • title：数据模型的标题。
  • description：数据模型的描述。
  • type：数据模型的类型。
  • format：数据模型的格式。

4. 路径注解

以下注解用于描述 API 的路径：

@Path

• 描述：用于定义路径参数。
• 可用于：方法。
• 属性：
  • value：路径参数的名称。

@PathVariable

• 描述：用于描述路径参数。
• 可用于：方法的参数。
• 属性：
  • value：路径参数的名称。

@RequestParam

• 描述：用于描述查询参数。
• 可用于：方法的参数。
• 属性：
  • value：查询参数的名称。
  • required：查询参数是否必需，默认为 false。

@RequestBody

• 描述：用于描述请求体。
• 可用于：方法的参数。

5. 响应注解

以下注解用于描述 API 的响应结果：

@ApiResponse

• 描述：用于描述响应结果。
• 可用于：方法。
• 属性：
  • responseCode：响应的状态码。
  • description：响应的描述。
  • content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

• 描述：用于描述响应结果的内容。
• 可用于：方法。
• 属性：
  • mediaType：内容的媒体类型。
  • schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

• 描述：用于描述数据模型的属性。
• 可用于：方法、类、接口。
• 属性：
  • title：数据模型的标题。
  • description：数据模型的描述。
  • type：数据模型的类型。
  • format：数据模型的格式。

6.使用示例

当使用Swagger 3注解编写API文档时，以下是一个示例代码，演示了如何使用各种注解来描述API的信息、请求参数和响应结果：

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用于管理用户信息")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    @Operation(summary = "根据ID获取用户信息", description = "根据用户ID查询用户的详细信息")
    @ApiResponse(responseCode = "200", description = "成功获取用户信息")
    @ApiResponse(responseCode = "404", description = "未找到对应用户")
    public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
        User user = userService.getUserById(id);
        if (user != null) {
            return ResponseEntity.ok(user);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @PostMapping
    @Operation(summary = "创建用户", description = "创建新用户")
    @ApiResponse(responseCode = "201", description = "成功创建用户")
    public ResponseEntity<User> createUser(@RequestBody CreateUserRequest request) {
        User user = userService.createUser(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新用户信息", description = "根据用户ID更新用户的信息")
    @ApiResponse(responseCode = "200", description = "成功更新用户信息")
    @ApiResponse(responseCode = "404", description = "未找到对应用户")
    public ResponseEntity<User> updateUser(@PathVariable("id") Long id, @RequestBody UpdateUserRequest request) {
        User user = userService.updateUser(id, request);
        if (user != null) {
            return ResponseEntity.ok(user);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "删除用户", description = "根据用户ID删除用户")
    @ApiResponse(responseCode = "204", description = "成功删除用户")
    @ApiResponse(responseCode = "404", description = "未找到对应用户")
    public ResponseEntity<Void> deleteUser(@PathVariable("id") Long id) {
        boolean deleted = userService.deleteUser(id);
        if (deleted) {
            return ResponseEntity.noContent().build();
        } else {
            return ResponseEntity.notFound().build();
        }
    }
}

在上述示例中，我们使用了@Tag注解来分组API，@Operation注解来描述每个API操作的摘要和详细描述，@ApiResponse注解来描述响应结果，@PathVariable注解来描述路径参数，@RequestBody注解来描述请求体，以及@ApiResponse和@ApiResponse注解来描述响应结果。