本文共 1112 字，大约阅读时间需要 3 分钟。

Swagger @ApiIgnore 注解的使用与应用

Swagger 是一个广泛使用的 API 文档生成工具，它通过注解机制帮助开发者快速生成 API 文档。其中，@ApiIgnore 注解是一个强大的工具，可以用来隐藏不需要公开的接口或参数，从而保护 API 的安全性和稳定性。

1. @ApiIgnore 在类级的应用

当 @ApiIgnore 注解应用于类级时，整个类及其所有方法都会被忽略。这意味着调用该类的任何 API 都不会被 Swagger 给出文档支持。这种情况下，可以通过在类级注解中设置 hidden 属性来进一步确认该类的隐藏状态。

@Api(value = "xxx", tags = "xxx", hidden = true)
@RestController
@RequestMapping("/xxx")
public class XxxController {
    // 该类及其所有方法都会被忽略
}

2. @ApiIgnore 在方法级的应用

当 @ApiIgnore 注解应用于方法级时，只有该方法及其参数会被忽略，而类级的其他方法和类别仍然会被文档生成。这对于需要对某些特定方法或参数进行隐藏而不影响其他 API 的开发者来说是一个非常有用的功能。

3. @ApiIgnore 在参数级的应用

@ApiIgnore 注解不仅可以应用于类和方法，还可以应用于方法参数。这对于那些包含敏感信息或不需要公开的参数来说尤为重要。通过在参数级使用 @ApiIgnore，可以确保这些参数不会被包含在 Swagger 文档中，从而保护数据安全。

4. 使用场景

• 保护内部接口：对于公司内部使用的私有接口，可以使用 @ApiIgnore 将其隐藏，使其不被外部访问。
• 隐藏敏感信息：对于包含敏感数据的参数或返回值，可以通过 @ApiIgnore 隐藏，以防止信息泄露。
• 简化文档：对于那些不需要公开的接口或参数，可以通过 @ApiIgnore 将其从 Swagger 文档中移除，简化用户的操作。

5. 注意事项

• 谨慎使用：@ApiIgnore 注解虽然强大，但仍需谨慎使用。确保隐藏的接口和参数不会影响到正常的业务流程。
• 文档清理：在使用 @ApiIgnore 后，建议定期清理 Swagger 文档，确保隐藏的接口和参数确实不再需要公开。
• 团队协作：在项目中使用 @ApiIgnore 时，需与团队成员保持沟通，明确隐藏的接口和参数的原因，以便在需要时能够快速更改。

通过合理使用 Swagger @ApiIgnore 注解，可以有效地保护 API 的安全性和稳定性，同时简化文档管理流程。

转载地址：http://wjqfk.baihongyu.com/