1. 概述
在使用 Spring Boot 生成 Swagger 文档时，我们常常需要将某些接口从公开文档中隐藏。这种需求很常见，比如：
- ✅ 某个接口还在开发中，尚未完成，不希望前端或其他协作方提前看到
- ✅ 存在一些内部或管理类接口（如健康检查、监控、定时任务触发等），仅限内部调用，无需暴露给外部使用者
本文将介绍几种简单粗暴但有效的方式，帮助你在 Swagger UI 中隐藏指定的接口或整个控制器。核心思路是通过注解控制文档生成逻辑，适用于主流的 Swagger（Springfox）和 OpenAPI v3（springdoc-openapi）方案。
⚠️ 注意：本文面向已有 Swagger 集成经验的开发者，默认你已经完成了基础配置。若还未接入，请先参考官方文档完成集成。
2. 使用 @ApiIgnore 隐藏单个接口
@ApiIgnore 是 Springfox 提供的一个经典注解，作用是告诉 Swagger 忽略被标注的方法或类，不会将其纳入生成的 API 文档中。
示例代码：
@ApiIgnore
@ApiOperation(value = "This method is used to get the author name.")
@GetMapping("/getAuthor")
public String getAuthor() {
return "Umang Budhwar";
}
✅ 效果：/getAuthor 接口将不会出现在 Swagger UI 中。
📌 小贴士：即使该方法上有 @ApiOperation，只要加上 @ApiIgnore，Swagger 依然会忽略它——优先级很高。
3. 使用 @ApiOperation(hidden = true) 隐藏接口
如果你不想引入额外注解，也可以直接利用 @ApiOperation 自带的 hidden 属性。
示例代码：
@ApiOperation(value = "This method is used to get the current date.", hidden = true)
@GetMapping("/getDate")
public LocalDate getDate() {
return LocalDate.now();
}
✅ 效果：同上，接口不会出现在文档中。
📌 对比：
- ✅
@ApiOperation(hidden = true)更细粒度，适合只想隐藏某个操作但保留其他 Swagger 元信息的场景 - ❌ 缺点是必须加
@ApiOperation，否则hidden属性无效（有些方法可能本来没加这个注解）
所以如果你只是为了隐藏，推荐直接用 @ApiIgnore，更直观。
4. 使用 @ApiIgnore 隐藏整个控制器
有时候我们希望一整个 Controller 都不进文档，比如运维用的 AdminController 或调试用的 TestController。
这时可以直接把 @ApiIgnore 加在类上：
@ApiIgnore
@RestController
@RequestMapping("/admin")
public class AdminController {
@GetMapping("/restart")
public String restartApp() {
// 重启应用逻辑
return "Restarted";
}
@GetMapping("/clearCache")
public String clearCache() {
// 清除缓存
return "Cache cleared";
}
}
✅ 效果：该 Controller 下所有接口都不会出现在 Swagger 文档中。
⚠️ 注意：不仅仅是接口，整个 Controller 分组也会从文档中消失，Swagger UI 上完全看不到。
6. 使用 @Hidden 隐藏单个接口（OpenAPI v3）
如果你使用的是 OpenAPI 3（即基于 springdoc-openapi 的方案，而不是老的 Springfox），推荐使用 @Hidden 注解。
它是 OpenAPI 官方支持的方式，语义清晰，功能稳定。
示例代码：
@Hidden
@GetMapping("/getAuthor")
public String getAuthor() {
return "Umang Budhwar";
}
✅ 效果：接口从 Swagger UI 中隐藏。
📌 适用场景：项目已升级到 springdoc-openapi-ui，建议统一使用 @Hidden 替代 @ApiIgnore。
7. 使用 @Hidden 隐藏整个控制器（OpenAPI v3）
同样地，@Hidden 也可以标注在类级别，用于隐藏整个控制器：
@Hidden
@RestController
public class RegularRestController {
@GetMapping("/test")
public String test() {
return "This won't show in docs";
}
}
✅ 效果：整个 Controller 及其所有接口均不出现在文档中。
💡 提示：@Hidden 支持方法和类级别，使用灵活，是 OpenAPI 下的首选方案。
⚠️ 注意事项：
@Hidden仅适用于 springdoc-openapi（OpenAPI v3）- 在 Springfox 中不生效（未来版本可能支持，但目前别指望）
8. 总结与选型建议
| 场景 | 推荐方式 | 适用方案 |
|---|---|---|
| 隐藏单个接口 | ✅ @ApiIgnore 方法级 |
Springfox |
| 隐藏整个 Controller | ✅ @ApiIgnore 类级 |
Springfox |
| 隐藏接口（OpenAPI v3） | ✅ @Hidden 方法级 |
springdoc-openapi |
| 隐藏 Controller（OpenAPI v3） | ✅ @Hidden 类级 |
springdoc-openapi |
想临时隐藏且已有 @ApiOperation |
✅ hidden = true |
Springfox |
📌 实战建议：
- 老项目用 Springfox → 统一使用
@ApiIgnore - 新项目用 OpenAPI v3 → 统一使用
@Hidden - ❌ 不要混用，避免维护混乱
✅ 所有示例代码均可在 GitHub 找到：
- Springfox（Swagger）示例：https://github.com/eugenp/tutorials/tree/master/spring-boot-modules/spring-boot-swagger-springfox
- OpenAPI v3 示例：https://github.com/eugenp/tutorials/tree/master/spring-boot-modules/spring-boot-springdoc
踩坑提醒：升级到 springdoc 后发现 @ApiIgnore 不生效？那是正常的——赶紧换成 @Hidden！