从0到1：Spring Boot + Swagger 打造可视化API文档

作为Java后端开发者，你是否曾为编写API文档头疼？手写文档易过时、接口变更同步不及时、前端对接反复沟通……这些问题，Swagger 或许能一次性解决。今天就带你从0到1，在Spring Boot项目中集成Swagger，让API文档“自动生成、实时更新、在线调试”。

一、为什么选择Swagger？

Swagger（现更名为OpenAPI）是一套API开发工具链，核心优势在于：

• 自动生成文档：通过代码注解，无需手动编写Markdown或Word；
• 实时同步：接口参数、返回值变更时，文档自动更新；
• 在线调试：支持直接在文档页面发送请求，验证接口功能；
• 团队协作友好：前后端开发者可通过同一文档对齐需求，减少沟通成本。

二、Spring Boot集成Swagger3.0（最新版）

Swagger3.0（OpenAPI 3.0）相比旧版更轻量，配置更简单，以下是具体步骤：

1. 引入依赖

在pom.xml中添加Swagger3.0的starter依赖（无需额外引入UI，已内置）：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. 核心配置类

创建SwaggerConfig配置类，通过注解定制文档信息：

@Configuration
@EnableOpenApi // 开启Swagger3.0（替代旧版@EnableSwagger2）
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30) // 指定OpenAPI版本
                .apiInfo(apiInfo())
                .select()
                // 扫描指定包下的接口（替换为你的Controller包路径）
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any()) // 匹配所有路径
                .build();
    }

    // 文档基本信息（标题、描述、版本等）
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户管理系统API文档")
                .description("包含用户CRUD、权限验证等接口")
                .version("1.0.0")
                .contact(new Contact("技术团队", "https://example.com", "tech@example.com"))
                .build();
    }
}

3. 接口添加Swagger注解

在Controller和实体类上添加注解，让文档更清晰：

• Controller类：用@Api(tags = "用户接口")标记模块；
• 接口方法：用@ApiOperation("获取用户列表")描述接口功能；
• 参数/实体类：用@ApiParam("用户ID")或@ApiModelProperty("用户名")说明字段含义。

示例Controller：

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户接口")
public class UserController {

    @GetMapping
    @ApiOperation("获取所有用户")
    public List<User> listUsers() {
        // 业务逻辑
        return Arrays.asList(new User(1L, "张三", 25));
    }

    @PostMapping
    @ApiOperation("创建用户")
    public User createUser(@RequestBody @Valid User user) {
        // 业务逻辑
        return user;
    }
}

示例实体类：

@Data
@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户ID")
    private Long id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("年龄")
    private Integer age;
}

三、访问与使用Swagger文档

启动Spring Boot项目后，访问以下地址即可打开Swagger UI：

http://localhost:8080/swagger-ui/index.html

页面上会清晰展示所有接口：

• 点击接口可展开查看请求方式、参数、返回值；
• 点击“Try it out”可输入参数，直接发送请求调试；
• 支持导出JSON/YAML格式的OpenAPI文档，方便导入Postman等工具。

四、生产环境注意事项

Swagger文档包含接口细节，生产环境需关闭！可通过配置文件控制：

# application-prod.yml（生产环境配置）
springfox:
  documentation:
    enabled: false

总结

Swagger不是银弹，但它能解决API文档的“痛点”：让文档从“负担”变成“工具”。只需几行配置和注解，就能让你的接口文档“活”起来，大幅提升团队协作效率。赶紧在你的Spring Boot项目中试试吧！

（全文约750字）