Swagger注解全攻略：一文搞懂 @ApiIgnore 的妙用！

🏆本文收录于「滚雪球学SpringBoot」(全网一个名)专栏，希望能够助你一臂之力，帮你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

🖋️ 前言

哈咯，我是bug菌，同学们早上好呀！今天要跟大家聊点 Swagger 相关的"冷门"小技巧------@ApiIgnore。相信很多小伙伴可能在使用 Swagger 组件做接口文档时，都只是使用些简单的 @Api、@ApiOperation 等常用注解，但在实际项目中，总会有些接口是不用暴露 的，比如那些专供内部使用的接口。这个时候，我们的@ApiIgnore就漂亮登场啦！✨它能够实现我们想要的接口隐藏功能。

今天我不仅会详细解释这个注解的用法，还会带大家拓展思路，结合实际案例教大家如何优雅地隐藏不必要的接口。话不多说，Let's go！🎢

📑 目录

1. 😎 什么是@ApiIgnore？
2. 🤔 为什么需要@ApiIgnore？
3. 🧰 @ApiIgnore的基本用法
4. 🔍 进阶案例：如何灵活使用@ApiIgnore
5. 📈 延伸思考：@ApiIgnore的局限性与解决方法
6. 🤹‍♀️ 总结：精通Swagger注解，让你的API文档更干净！

😎 什么是@ApiIgnore？

老规矩，我们先来剖析下它的原理。首先@ApiIgnore 注解，它是 Swagger 提供的一个非常实用的注解，用来忽略接口、类或者参数，让它们在生成的 API 文档中"消失"。一般来说，它主要应用于以下几个场景：

• 内部接口：那些只用于内部调用的接口，不希望暴露给外部开发者。
• 调试接口：为了测试或调试创建的临时接口，不希望在正式文档中出现。
• 敏感接口：一些敏感的管理操作接口，比如数据清理、账户管理等，不适合直接展示在 API 文档中。

简单来说，@ApiIgnore 就是一个低调的保镖，默默守护着 API 文档的干净与安全，有木有有木有🙈

🤔 为什么需要@ApiIgnore？

如果有同学对此有疑问，那大概想说，为什么需要@ApiIgnore？直接把接口注释不行吗？如果你在项目中使用 Swagger 来生成接口文档，肯定遇到过这样的情况：文档里展示了很多"无关紧要"的接口，让其他开发者觉得眼花缭乱 ，甚至觉得你们的 API "没啥规范"。这个时候，@ApiIgnore 可以帮你隐藏这些"杂项"，让文档看起来更简洁、专业，也更方便他人查阅！

举个简单的例子，公司内部可能有一个专门用于定时任务管理的接口，这个接口不希望被外部调用或误用。如果没有@ApiIgnore，它就会出现在文档中，给外部前端同事带来困扰。于是，我们可以用@ApiIgnore让它从文档中"消失"。✨是不是很神奇？接着我会给大家做个实例演示。

首先我们已经集成了Swagger，我们正常启动起来，可以看到user类相关的接口文档，共有5个对吧。

现在，比如我们要对某个接口进行隐藏，那我们只需要在对应的接口上加上@ApiIgnore 注解，例如，给删除接口加上注解，代码如下：

    @ApiIgnore
    @ApiOperation("删除user")
    @DeleteMapping("/{ids}")
    public R<Void> remove(@PathVariable Long[] ids) {
        return toR(userService.deleteByIds(ids));
    }

接着重启项目后，我们再次刷新Swagger管理页，我们可以清晰的看到，删除user这个接口没有在界面上展示了。截图展示如下：

  明显可以看到，针对删除user这个接口请求被成功隐藏了。

🧰 @ApiIgnore的基本用法

接下来，我会逐步讲解@ApiIgnore的三种基本用法，让大家能轻松上手。👨‍🏫

1. 忽略整个控制器类

假设我们有一个控制器InternalController，里面的接口不希望出现在文档中，这时候可以直接在类上加@ApiIgnore注解：

import springfox.documentation.annotations.ApiIgnore;

@ApiIgnore
@RestController
@RequestMapping("/internal")
public class InternalController {

    @GetMapping("/task")
    public String getInternalTask() {
        return "Internal Task";
    }
}

这样整个控制器都不会出现在 Swagger 文档中了！🎩

2. 忽略单个接口方法

有时候，我们只想隐藏某个特定的方法。此时可以直接在方法上使用@ApiIgnore注解：

@RestController
@RequestMapping("/api")
public class UserController {

    @GetMapping("/public")
    public String publicApi() {
        return "Public API";
    }

    @ApiIgnore
    @GetMapping("/internal")
    public String internalApi() {
        return "Internal API";
    }
}

在这个例子中，/api/public接口会出现在文档中，而/api/internal则被"隐藏"起来，只有知道具体路径的开发者才能调用。

3. 忽略参数

有时候，我们并不想在文档中展示某些参数，尤其是那些系统自动生成 的参数。@ApiIgnore也可以用在参数上，轻松搞定：

@GetMapping("/user")
public String getUser(
    @ApiIgnore @RequestParam String internalId, 
    @RequestParam String username) {
    return "User Info";
}

上面的代码会在文档中隐藏internalId参数，避免误导外部调用者。

🔍 进阶案例：如何灵活使用@ApiIgnore

接下来，我将展示一个稍微复杂一些的案例，帮助大家理解如何更好地应用@ApiIgnore。📊

需求：隐藏管理后台接口

假设我们有一个电商项目，用户接口和管理后台接口都在同一个控制器中。我们希望用户能看到公开的商品接口，但不希望管理后台的商品管理接口被暴露出来。这时候，我们可以在管理后台接口上添加@ApiIgnore。

@RestController
@RequestMapping("/product")
public class ProductController {

    @GetMapping("/list")
    public String listProducts() {
        return "Product List";
    }

    @ApiIgnore
    @PostMapping("/manage")
    public String manageProduct() {
        return "Manage Product";
    }
}

在这个例子中，/product/list 会出现在 Swagger 文档中，而 /product/manage 则不会出现。这不仅让文档更简洁，也提升了系统的安全性。😎

@ApiIgnore 注解原理

@ApiIgnore 注解，它主要用于 API 文档生成工具中（例如 Swagger），用于标记某些类、方法或字段在生成 API 文档时被忽略。这在实际开发中非常常见，当你希望某个接口或者字段不出现在自动生成的 API 文档中时，使用 @ApiIgnore 可以轻松解决。

1. @ApiIgnore 注解的用途

在开发过程中，可能会有一些方法或字段不希望暴露给外部接口文档。例如，一些用于内部处理的接口、敏感信息或者暂时不需要公开的字段，可以通过 @ApiIgnore 注解来屏蔽它们，使其不出现在自动生成的文档中。

常见的应用场景包括：

• 隐藏某些 API 接口： 一些接口只供内部使用，不希望它们在生成的 API 文档中展示。
• 隐藏字段： 某些数据字段可能包含敏感信息，或者不希望公开，使用 @ApiIgnore 可以屏蔽这些字段的展示。

2. @ApiIgnore 注解的源码

@ApiIgnore 注解通常和 Swagger API 文档生成工具一起使用。下面是 @ApiIgnore 注解的源码示例：

/**
 * This annotation can be used to mark a class, method, or field to be ignored in the Swagger documentation.
 */
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiIgnore {
}

核心元素分析：

• @Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })： 这个注解可以用于方法、类和字段，表示可以在这三种元素上使用 @ApiIgnore。
• @Retention(RetentionPolicy.RUNTIME)： 表示该注解将在运行时保留，因此在生成文档时，Swagger 可以反射获取到该注解，并忽略对应的元素。

3. 生成文档时的作用

@ApiIgnore 注解的作用并不直接在代码运行时体现，而是在生成 API 文档时，由文档生成工具（如 Swagger）进行处理。Swagger 解析类、方法和字段时，会根据反射机制检查是否存在 @ApiIgnore 注解。如果找到该注解，Swagger 会跳过这些类、方法或字段，防止它们出现在最终生成的 API 文档中。

3.1 Swagger 中的处理

在 Swagger 的代码中，通常会有类似于以下的逻辑来忽略被标注为 @ApiIgnore 的元素：

// 伪代码示例，展示如何忽略@ApiIgnore注解
public class ApiModelReader {

    public void read(ApiModel model) {
        // 获取所有的字段、方法或类
        for (Field field : model.getClass().getDeclaredFields()) {
            if (field.isAnnotationPresent(ApiIgnore.class)) {
                // 如果字段上标注了@ApiIgnore注解，跳过该字段
                continue;
            }
            // 其他处理逻辑
        }
    }
}

上面的伪代码示例中，Swagger 在解析模型时，会检查每个字段或方法是否带有 @ApiIgnore 注解。如果标记了该注解，则该字段会被忽略，不会出现在 API 文档中。

3.2 Springfox Swagger 中的处理

如果你使用的是 springfox-swagger2，则 @ApiIgnore 注解会在生成 Swagger 文档时被过滤掉。Springfox 的 Docket 配置类通常会集成这些注解，并通过反射检查每个 API 接口是否需要被忽略。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiIgnore.class).negate())  // 忽略@ApiIgnore标注的方法
            .paths(PathSelectors.any())
            .build();
    }
}

3.3 Swagger UI 中的效果

一旦应用了 @ApiIgnore 注解并通过 Swagger 生成文档，最终在 Swagger UI 或其他前端工具中生成的文档中，带有 @ApiIgnore 注解的 API 接口或字段将不再显示。这保证了文档的简洁和安全性，避免了将不该公开的接口或字段暴露给外部用户。

4. 小结

• @ApiIgnore 注解主要用于 API 文档生成工具（如 Swagger）中，标记那些不希望暴露在文档中的接口、方法或字段。
• 它通过反射机制配合文档生成工具进行处理，忽略被标注的元素。
• 在实际应用中，@ApiIgnore 主要用于隐藏不需要公开的内部接口或敏感数据字段，增强接口文档的安全性和简洁性。

通过使用 @ApiIgnore 注解，开发者可以轻松控制哪些内容出现在生成的 API 文档中，确保不必要的接口或敏感数据不会暴露给外部用户。

📈 延伸思考：@ApiIgnore的局限性与解决方法

1. ⚠️ 局限性

@ApiIgnore固然方便，但并不是万能的。例如：

• 隐藏接口的访问控制：虽然接口隐藏了，但外部开发者依然可以直接访问该路径。即便文档中不显示接口，仍然需要通过权限控制、身份认证等方式确保安全。
• 无选择性地隐藏 ：@ApiIgnore只能完全隐藏接口或参数，无法部分展示。如果希望对部分用户隐藏，而对另一些用户展示，需要更复杂的权限管理机制。

2. 🚀 解决方法

我们可以在安全层面进一步增强接口的隐藏效果。例如，结合 Spring Security 或 JWT 鉴权机制，在用户登录或权限检查上多做一些限制，确保只有内部人员可以访问"隐藏接口"。

🤹‍♀️ 总结：精通Swagger注解，让你的API文档更干净！

写到这里，你是不是已经对@ApiIgnore的用法了然于心了呢？这小小的注解虽然不常见，但却能让你的 API 文档更简洁、专业。如果你还没用过，赶紧在项目中尝试一下吧！记住，文档越干净，开发体验越愉悦！😁希望今天的分享对你有所帮助，大家一起继续探索 Swagger 的更多玩法吧！🎉

📣 关于我

我是bug菌，CSDN | 掘金 | InfoQ | 51CTO | 华为云 | 阿里云 | 腾讯云 等社区博客专家，C站博客之星Top30，华为云多年度十佳博主&最具价值贡献奖，掘金多年度人气作者Top40，掘金等各大社区平台签约作者，51CTO年度博主Top12，掘金/InfoQ/51CTO等社区优质创作者；全网粉丝合计 30w+ ；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试真题、4000G PDF电子书籍、简历模板等海量资料，你想要的我都有，关键是你不来拿。

-End-