【超详细】Java 开发必会，Swagger常用注解全家桶教学，让接口文档秒变艺术品（附代码示例）

原创已于 2025-04-20 17:26:58 修改 · 2.7k 阅读

17 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#java #开发语言

于 2025-03-18 09:22:58 首次发布

Java知识专栏收录该内容

338 篇文章

订阅专栏

Python3.8

Python 是一种高级、解释型、通用的编程语言，以其简洁易读的语法而闻名，适用于广泛的应用，包括Web开发、数据分析、人工智能和自动化脚本

一、Swagger 入门小剧场

二、基础注解三件套

1. @Api：给 Controller 打标签

2. @ApiOperation：给接口写说明书

3. @ApiParam：参数说明小能手

三、进阶注解大揭秘

4. @ApiModel & @ApiModelProperty：模型文档化

5. @ApiResponse & @ApiResponses：错误码管理

6. @ApiImplicitParam & @ApiImplicitParams：复杂参数处理

亲爱的读者朋友们，我是你们的 Java 小能手。今天想和大家聊聊 Swagger 这个神器，特别是它的常用注解。记得去年带小侄子学编程时，他总抱怨写接口文档像吃辣椒 —— 又辣又不得不吃。现在有了 Swagger，这事儿就像给文档加了层蜂蜜，又甜又顺畅！

一、Swagger 入门小剧场

想象一下，你是火锅店的大厨，每天要给服务员写菜单。如果每次都用 A4 纸手写，不仅麻烦还容易出错。Swagger 就像电子点餐系统，既能让顾客直观看到菜品（接口信息），还能直接下单试吃（调试接口）。今天咱们就来拆解这个 "点餐系统" 的核心组件 —— 注解。

二、基础注解三件套

1. @Api：给 Controller 打标签

就像火锅店的招牌，@Api 用来标记整个 Controller 的信息。比如：

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理模块", description = "提供用户增删改查接口")
public class UserController {
    // ...
}

这里的tags就像菜单分类，description是菜品简介。记得去年给团队做培训时，有个新手把tags写成复数形式，结果 Swagger 页面显示乱码，这个细节要注意哦！

2. @ApiOperation：给接口写说明书

每个接口就像一道菜，@ApiOperation 就是菜品详情：

@GetMapping("/{id}")
@ApiOperation(value = "根据ID查询用户", 
            notes = "支持缓存查询，响应时间<500ms",
            httpMethod = "GET")
public User getUser(@PathVariable Long id) {
    // ...
}

value是菜名，notes是烹饪秘籍。曾经有个同事把notes写成description，结果文档里没显示，后来才发现这是个常见误区。

3. @ApiParam：参数说明小能手

服务员上菜时要报菜名，@ApiParam 就是参数的 "菜名"：

@PostMapping
@ApiOperation("创建新用户")
public User createUser(
    @ApiParam(value = "用户姓名", required = true, example = "张三") String name,
    @ApiParam(value = "用户年龄", defaultValue = "18") Integer age
) {
    // ...
}

这里的required就像标明这道菜是否必点，example是推荐搭配。记得把required设为 true 时，Swagger UI 会自动校验必填参数哦！

三、进阶注解大揭秘

4. @ApiModel & @ApiModelProperty：模型文档化

就像火锅店的食材清单，这两个注解专门管理数据模型：

@ApiModel(value = "用户实体", description = "系统用户基本信息")
public class User {
    @ApiModelProperty(value = "用户ID", example = "12345")
    private Long id;
    
    @ApiModelProperty(value = "用户姓名", required = true)
    private String name;
}

我曾遇到过一个诡异的问题：模型属性在 Swagger 里不显示。后来发现是忘记给类加 @ApiModel，这个教训让我在代码审查时特别留意这一点。

5. @ApiResponse & @ApiResponses：错误码管理

服务员要知道菜品的退换规则，@ApiResponse 就是接口的错误说明：

@GetMapping("/{id}")
@ApiOperation("查询用户")
@ApiResponses({
    @ApiResponse(code = 200, message = "查询成功"),
    @ApiResponse(code = 404, message = "用户不存在", response = ErrorResult.class)
})
public User getUser(@PathVariable Long id) {
    // ...
}

这里可以指定错误响应的具体模型，比如ErrorResult类。有一次线上接口突然返回 500 错误，但 Swagger 文档没说明，导致前端同事抓瞎，后来加上这个注解后问题迎刃而解。

6. @ApiImplicitParam & @ApiImplicitParams：复杂参数处理

有些接口需要特殊参数，比如分页查询：

@GetMapping("/list")
@ApiOperation("分页查询用户")
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNum", value = "页码", defaultValue = "1"),
    @ApiImplicitParam(name = "pageSize", value = "每页数量", defaultValue = "10")
})
public Page<User> listUsers() {
    // ...
}

这种注解常用于非 @RequestBody 参数，比如 URL 中的查询参数。我见过最复杂的案例是给一个搜索接口加了 12 个参数，用这种方式管理后文档清爽多了。

四、实战技巧与避坑指南

分组管理技巧：在 @Api 中使用position属性调整模块顺序，就像给菜单排序。
版本控制：在@RequestMapping中加入/v1，Swagger 会自动生成版本标签。
忽略某些接口：用@ApiIgnore注解跳过不需要文档化的接口，比如健康检查接口。
文档缓存问题：如果修改注解后页面没更新，试试在配置类里禁用缓存：

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .enable(true) // 生产环境记得设为false
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example"))
        .build();
}

五、写给家人的建议

代码规范：建议在团队内统一注解使用规范，比如@ApiOperation的value必须用动宾结构（如 "创建用户"）。
持续维护：接口变更时同步更新注解，否则文档会变成 "过期菜单"。
结合测试：利用 Swagger UI 的在线测试功能，减少接口联调时间。

六、常见问题解答

Q：为什么我的注解在 Swagger 里不显示？
A：检查是否漏掉了 @EnableSwagger2 注解，或者包扫描路径是否正确。

Q：可以自定义 UI 主题吗？
A：可以通过引入 swagger-ui-dist 的 CSS 文件进行定制，我之前给公司项目改成了星空主题，效果超赞！

Q：如何处理敏感信息？
A：用@ApiModelProperty(hidden = true)隐藏敏感字段，或者在配置类中过滤。