在前后端分离的项目里，API 就是后端和前端之间的“普通话”。但问题是——
接口改了，文档没跟上？联调时反复问参数格式？测试要手动拼 JSON？
别慌，Swagger2 来救场。
它能让你的接口自动生成在线文档 + 支持一键测试，真正做到“代码即文档”。
下面看看怎么在 Spring Boot 项目中用好它。
1. 实体类：让字段也有“说明书”
先定义一个 User 类：
import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel("用户实体") public class User { @ApiModelProperty("用户ID") private Long id; @ApiModelProperty("用户名") private String username; @ApiModelProperty("密码（明文）") private String password; // getter / setter 省略 }
@ApiModel：给整个类加个标题；@ApiModelProperty：给每个字段写说明。
这样，在 Swagger UI 的请求/响应示例中，字段含义一目了然，再也不用猜 name 到底是昵称还是真实姓名。
2. Controller：标注接口用途和参数
再来看一个典型的 Controller：
@RestController @RequestMapping("/swagger") @Api("用户管理接口") // 整个 Controller 的分组名称 public class TestController { @GetMapping("/get/{id}") @ApiOperation("根据ID查询用户") // 接口功能描述 public JsonResult<User> getUserInfo( @PathVariable @ApiParam("用户唯一标识") Long id // 路径参数说明 ) { return new JsonResult<>(new User(id, "张三", "123456")); } @PostMapping("/insert") @ApiOperation("新增用户") public JsonResult<Void> insertUser( @RequestBody @ApiParam("用户对象") User user // 请求体说明 ) { // 保存逻辑 return JsonResult.success(); } }
关键注解说明：
| 注解 | 作用 |
@Api |
标识这个 Controller 是 Swagger 的资源，用于分组显示 |
@ApiOperation |
描述这个接口是干啥的 |
@ApiParam |
解释某个参数的含义（可用于 @PathVariable、@RequestParam、@RequestBody） |
3. 效果：打开浏览器，接口“活”了
启动项目，访问：
http://localhost:8080/swagger-ui.html
你会看到：
- 所有接口按 Controller 分组；
- 每个接口有清晰的描述、参数说明、请求方式；
- 点击 “Try it out”，直接填参数 → 发送 → 查看 JSON 响应！
比如测试 /swagger/get/1，输入 ID=1，立刻看到返回：
{ "code": 200, "data": { "id": 1, "username": "张三", "password": "123456" } }
连 Postman 都省了。
对于 POST 接口，Swagger 还会自动生成 JSON 示例模板，你只需修改字段值即可提交。
4. 小贴士
- 不要暴露到生产环境：通过配置控制 Swagger 开关，避免接口信息泄露；
- 配合统一返回结构（如
JsonResult<T>），文档更规范； - 字段说明写清楚，前端同学会感谢你；
- 虽然 Swagger2 已停止维护（推荐新项目用 Springdoc OpenAPI），但在 Spring Boot 2.x 项目中，2.2.2 或 2.9.2 版本依然稳定好用。
