使用Swagger 3注解编写API文档详解

在现代软件开发中，API文档的编写是至关重要的一环，它不仅能帮助开发者理解和正确使用API，还能提升团队协作效率。Swagger 3是一个流行的API文档规范，通过注解的方式可以清晰地定义API的各个方面。本文将深入探讨Swagger 3中常用的注解及其使用方法。

@OpenAPIDefinition 和 @Info

@OpenAPIDefinition 注解用于定义整个API文档的基本信息，通常应用于类或接口。

属性：
- info：指定 @Info 注解的对象，用于描述API文档的基本信息。

@Info 注解用于定义API文档的基本信息。

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

@OpenAPIDefinition(info = @Info(
    title = "用户管理API",
    description = "用于管理用户信息的API接口文档",
    version = "1.0.0",
    termsOfService = "https://example.com/terms",
    contact = @Contact(name = "API支持", url = "https://example.com/support", email = "support@example.com"),
    license = @License(name = "Apache 2.0", url = "http://www.apache.org/licenses/LICENSE-2.0.html")
))

@Tag

@Tag 注解用于给API分组，类似于为API文档添加标签，便于组织和查找。

属性：
- name：分组的名称。
- description：分组的描述。

@Tag(name = "用户管理", description = "用于管理用户信息的API")

@Operation 和 @ApiResponse

@Operation 注解用于描述API的操作，通常应用于方法上。

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

@Operation(summary = "根据ID获取用户信息", description = "根据用户ID查询用户的详细信息")
@ApiResponse(responseCode = "200", description = "成功获取用户信息")
@ApiResponse(responseCode = "404", description = "未找到对应用户")

@Parameter 和 @RequestBody

@Parameter 注解用于描述API操作的输入参数。

属性：
- name：参数的名称。
- in：参数的位置，可以是 path、query、header、cookie 中的一种。
- description：参数的描述。
- required：参数是否必需，默认为 false。
- schema：指定 @Schema 注解的对象，用于描述参数的数据类型。

@RequestBody 注解用于描述API操作的请求体。

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

public ResponseEntity<User> getUserById(@PathVariable("id") Long id)

@Schema

@Schema 注解用于描述数据模型的属性，可用于方法、类、接口。

属性：
- title：数据模型的标题。
- description：数据模型的描述。
- type：数据模型的类型。
- format：数据模型的格式。

@Schema(title = "用户信息", description = "描述用户的基本信息")
public class User {
    // User类的字段和方法
}

示例代码分析

下面是一个示例代码，演示了如何使用Swagger 3注解来编写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();
        }
    }
}