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 注解,例如,给删除接口加上注解,代码如下:

json 复制代码
    @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注解:

java 复制代码
import springfox.documentation.annotations.ApiIgnore;

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

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

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

2. 忽略单个接口方法

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

java 复制代码
@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也可以用在参数上,轻松搞定:

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

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

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

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

需求:隐藏管理后台接口

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

java 复制代码
@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 注解的源码示例:

java 复制代码
/**
 * 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 的元素:

java 复制代码
// 伪代码示例,展示如何忽略@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 接口是否需要被忽略。

java 复制代码
@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-

相关推荐
PetterHillWater1 分钟前
基于Trae智能复杂项目重构实践
后端·aigc
东阳马生架构14 分钟前
订单初版—2.生单链路中的技术问题说明文档
java
凌览14 分钟前
有了 25k Star 的MediaCrawler爬虫库加持,三分钟搞定某红书、某音等平台爬取!
前端·后端·python
这里有鱼汤26 分钟前
给你的DeepSeek装上实时行情,让他帮你炒股
后端·python·mcp
咖啡啡不加糖28 分钟前
暴力破解漏洞与命令执行漏洞
java·后端·web安全
风象南31 分钟前
SpringBoot敏感配置项加密与解密实战
java·spring boot·后端
DKPT41 分钟前
Java享元模式实现方式与应用场景分析
java·笔记·学习·设计模式·享元模式
Percep_gan1 小时前
idea的使用小技巧,个人向
java·ide·intellij-idea
ん贤1 小时前
RESTful风格
后端·go·restful
缘来是庄1 小时前
设计模式之迭代器模式
java·设计模式·迭代器模式