Swagger/OpenAPI 完全指南：自动生成 API 文档

Swagger 是最流行的 API 文档工具。本文介绍 Swagger 的使用方法。

Spring Boot 集成

添加依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

访问地址

http://localhost:8080/swagger-ui.html
http://localhost:8080/v3/api-docs

注解使用

@Tag(name = "用户管理", description = "用户CRUD接口")
@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @Operation(summary = "查询用户列表", description = "分页查询用户")
    @GetMapping
    public Page<User> list(
            @Parameter(description = "页码") @RequestParam(defaultValue = "1") int page,
            @Parameter(description = "每页数量") @RequestParam(defaultValue = "10") int size) {
        return userService.list(page, size);
    }
    
    @Operation(summary = "创建用户")
    @PostMapping
    public User create(@RequestBody @Valid UserDTO dto) {
        return userService.create(dto);
    }
}

API 信息配置

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("用户管理系统 API")
                .version("1.0.0")
                .description("用户管理系统接口文档"));
    }
}

最佳实践

1. 注解完整：每个接口都要有注解
2. 分组管理：按模块分组
3. 版本管理：不同版本不同文档
4. 在线测试：使用 Swagger UI 测试接口

总结

Swagger 让 API 文档自动生成，减少了手动维护文档的工作量。