范文健康探索娱乐情感热点
投稿投诉
热点动态
科技财经
情感日志
励志美文
娱乐时尚
游戏搞笑
探索旅游
历史星座
健康养生
美丽育儿
范文作文
教案论文
国学影视

Java中让Swagger产出符合诉求的文档,按需决定显示或者隐藏内容

  swagger作为一个被广泛使用的在线接口文档辅助工具,上手会用很容易,但想用好却还是需要一定功夫的。所以呢,本篇文档就和大家一起来聊一聊如何用好swagger,让其真正的成为我们项目交付过程中的神兵利器。 更改接口文档总标题与描述
  默认的情况下,Swagger的界面整个文档的名称以及描述内容都是通用值,这会让人拿到文档之后比较困惑,无法知晓这是哪个项目哪个系统哪个服务提供的接口,也不知道接口是哪个团队负责,哪位开发人员维护的。
  比如下面这样:
  为了体现出接口文档的专业性,让人更容易知晓此接口文档所属系统、对应版本、维护团队等信息,我们可以在代码中根据需要自定义相关的内容。
  比如: @Bean public Docket createRestApi() {     ApiInfo apiInfo = new ApiInfoBuilder()         .title("资源管理系统接口文档")         .description("资源管理模块对外供APP/WEB端调用的接口详细文档描述")         .version("v1.0.0")         .contact(new Contact("架构悟道", "https://juejin.cn/user/1028798616709294","veezean@outlook.com"))         .termsOfServiceUrl("https://juejin.cn/user/1028798616709294")         .license("Apache License")         .licenseUrl("http://xxx")         .build();     return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select().build(); }
  重新启动并查看界面,可以发现界面上相关内容已经变更为我们自定义的内容了,是不是比改动前显得更加明晰与专业了?
  上述swagger中支持自定义的描述性的字段信息,梳理如下:
  字段
  含义描述
  title
  接口文档的 ​文档标题​  ​
  description
  接口文档的详细​ ​整体描述​  ​说明
  version
  接口文档对应的​ ​版本​  ​信息
  termsOfServiceUrl
  此接口文档的提供团队对应的​ ​团队url​  ​地址
  contact
  负责此部分接口的联系人信息,包含​ ​姓名​  ​​、​ ​邮箱​  ​​、​ ​主页url​  ​地址等
  license
  指定接口所遵循的​ ​License协议​  ​版本
  licenseUrl
  此接口所遵循的License协议对应的详细介绍​ ​url地址​  ​按需显示/隐藏相关接口内容
  手动编写接口文档的时候,我们可以根据实际情况灵活的去控制需要写入到文档中的接口内容、以及接口的请求响应体中的字段信息 —— 因为并不是系统中提供的所有的接口都需要体现在接口文档中暴露给调用方去知晓的,比如有一些系统状态监控类的接口,只需要内部使用即可。
  对于Swagger而言,生成接口文档的时候,默认是扫描所有的@Controller中的全部接口方法全部显示到文档中,但其也贴心地考虑到了实际应用中的这种按需隐藏或者展示接口内容的诉求,并提供了多种不同的方式来支持。
  下面一起来看下。针对单个接口进行隐藏
  在单个接口方法的上方添加 @ApiOperation 注解说明,并指定 hidden = true即可将该接口从swagger界面能上隐藏:@GetMapping("/test") @ApiOperation(value = "内部测试接口", hidden = true) public String test() {     return "OK"; }
  启动进程,查看Swagger界面,发现该接口没有出现在界面上:
  隐藏整个Controller类中的接口
  如果整个Controller类下面所有的接口都需要隐藏,则可以在Conntroller类上添加上@ApiIgnore注解可以了。@RestController @RequestMapping("/test") @ApiIgnore public class TestController { // ... ignore ... }
  改动后重启进程,再打开swagger界面,发现TestController整个类的接口都没有显示。
  这里补充一句,因为用于描述Controller类的接口含义的注解@Api中也有个hidden属性,而且看其源码注释说明,如果设置hidden=true,应该也是将该Controller类整体隐藏。但是实际上测试发现并没有生效,这个实际使用的时候要小心这一点(基于swagger 2.7.0版本试验,不确定是否为BUG)。@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @Inherited public @interface Api {     /**      * Hides the operations under this resource.      *      * @return true if the api should be hidden from the swagger documentation      */     boolean hidden() default false; }仅显示指定package路径下的接口
  我们的项目里面经常会依赖或者引用一些三方jar包,而这些三方jar中有的时候也会提供一些接口,也会出现在我们的接口文档中,这样就会显得接口文档中存在很多不确定的内容。
  比如:
  因为这部分逻辑并非业务代码中提供的,所以我们没法按照上面的方式,修改源码添加hidden=true的方式来控制其不显示。这个时候,就需要按照package进行白名单控制的能力了。swagger还支持根据给定的basePackage以及paths进行组合控制,仅显示给定包下指定路径下的接口。@Bean public Docket createRestApi() {     ApiInfo apiInfo = new ApiInfoBuilder()             .title("资源管理系统接口文档")             .description("资源管理模块对外供APP/WEB端调用的接口详细文档描述")             .version("v1.0.0")             .build();     ApiSelectorBuilder selectorBuilder = (new Docket(DocumentationType.SWAGGER_2)).apiInfo(apiInfo).select();     selectorBuilder.apis(RequestHandlerSelectors.basePackage("com.jiagouwudao.resmanage"));     selectorBuilder.paths(PathSelectors.any());     return selectorBuilder.build(); }
  这样就可以保证出现在接口文档里面的都是我们自己定义的接口了。重新启动并刷新界面,会发现,只有指定package目录下的Controller接口显示在swagger界面上了。
  隐藏响应中不愿暴露的属性
  在项目开发过程中,如果我们的代码没有做强制的VO、DO隔断,出于减少编码量考虑,可能会使用同一个对象进行内部处理以及外部交互。比如:
  定义一个OperateLog对象,为数据库中T_OPERATE_LOG表所对应的实体类,用于记录每个用户的操作行为;同时也作为recordOperateLog接口的请求Body体,用于传递需要记录的用户操作信息。
  在上面的例子中:作为数据表实体类进行逻辑处理的时候,需要用到唯一主键id信息作为recordOperateLog接口的请求Body体时,调用方是不需要指定这条记录的ID值的(ID值会在存储到DB的时候自动由DB生成唯一自增主键)
  这种场景下,我们就希望提供出去的接口文档中,在对recordOperateLog接口的请求body体中字段说明的时候,就不要体现出id字段,避免让调用方产生疑惑,不知道id调用的时候应该如何赋值。我们可以通过在指定字段上添加@ApiModelProperty注解并指定hidden = true来将其从接口文档中隐藏掉。
  比如:@Data @ApiModel("操作记录信息") public class OperateLog {     @ApiModelProperty(value = "记录唯一ID,无实际意义", hidden = true)     private long id;     @ApiModelProperty("操作类型,取值说明:1,新增;2,更新;3,删除;4,查询")     private int operateType;     @ApiModelProperty("操作用户")     private String user;     @ApiModelProperty(value = "操作详情")     private String detail; }
  则界面中的接口文档不会显示id的有关信息(注意:仅接口文档中不体现,不会影响具体请求或者响应中此字段的实际值)。
  关闭生产环境的swagger
  考虑到生产环境的安全性,对于一些比较重要的系统,我们一般不太愿意将生产环境的接口文档暴露出来,避免对系统的运行埋下隐患。
  在SpringBoot项目中,我们会为不同的环境提供不同的配置文件, 然后在启动的时候使用 --spring.active.profile 来指定加载哪一份配置。
  如果需要使Swagger可以被访问,我们可以通过代码中添加@EnableSwagger2注解的方式来实现。若限制仅在开发或测试环境上允许swagger访问而生产环境不允许打开,则只需要让这个添加了@EnableSwagger2注解的类根据当前的运行环境来决定是否加载就可以了。借助SpringBoot提供的@Profile注解,我们可以这样来实现:@Configuration @EnableSwagger2 @Profile({"DEV", "TEST"}) public class SwaggerConfig {  }
  这样,就可以让SwaggerConfig类在profile=PROD的时候不会被加载,也就不会开启swagger的开关。使用 --spring.active.profile=PROD启动进程,尝试访问swagger界面,会发现无法打开:
  给Swagger换个皮肤
  默认的swagger界面所有内容都罗列居中显示,然后需要一层层的展开去,操作上面不太方便,整体界面风格也不太符合一个"文档"的样子。为了提升使用体验,可以借助开源的knife4j框架来让swagger变得更加好用。
  使用方式很简单,在已有的swagger依赖的基础上,在pom.xml中新增如下引用依赖:     com.github.xiaoymin     knife4j-spring-ui     2.0.4 
  启动进程后,访问 doc.html 页面,比如 http://127.0.0.1:8088/doc.html,可以发现一个更加符合接口文档体验的新的界面:
  当然,这里我们使用了knife4j最简单的一个"换肤"的特性,而作为一款优秀的开源工具,knife4j所提供的能力远不止这些,有兴趣的可以点击此处详细了解一下。总结
  好啦,关于如何补全Swagger接口的描述内容、如何自主决定某些内容的显示与隐藏等相关的内容,这里就给大家分享到这里啦。关于本篇内容你有什么自己的想法或独到见解么?

越南大学生也很卷?我,90后越南人,大学毕业回村,只能干体力活这是我们讲述的第884位真人的故事我叫杨高明越南杨高明,一个爱唱歌的越南苗族小伙。如果我告诉你,越南现在还有没水没电没网不通车的山村,你一定不相信或者觉得不可思议,但这确实是事实。欧冠0横扫比尔森胜利三连胜排名榜首萨内梅开二度北京时间10月5日凌晨0点45分,202223赛季欧洲冠军联赛小组赛第三轮C组,德甲豪门拜仁慕尼黑主场迎战捷克球队比尔森胜利。上半场,萨内格纳布里和马内各入一球下半场,萨内完成梅开宝宝的31项敏感期1。光感的敏感期03个月。2。味觉发育的敏感期47个月。3。口腔的敏感期412个月。4。手臂发育的敏感期612个月。5。大肌肉发育的敏感期12岁,小肌肉1。53岁。6。对细微事物感身高抑制剂被发现,牛奶也在其中?儿科医生少让孩子吃所有的父母,最大的愿望就是希望孩子聪明健康漂亮,长得好看,成绩优秀。这一定是大多数家长的心声。养一个孩子,不仅要优秀,更要能为父母争光。当别人羡慕你的孩子聪明健康时,父母自然会感到怀孕期间最佳作息时间,你做到了吗?孕妈妈们,你们怀孕前和怀孕后的作息时间有变化吗?想要聪明又高颜值的宝宝,乐观淡定姐强烈推荐这份怀孕期间最佳作息时间,一切为了宝宝好,各位妈妈们要加油咯!早上730800喝温水起床后汉字这么多,如何选择合适的字为男孩起名?因为汉字的数量实在是太多,所以为了区分它们,让大家查询汉字的时候更容易点,就产生了部首笔画笔顺拼音种种。这些虽是好辨别汉字,但在男孩取名字的时候,好像就不是那么好用了,那怎么给男孩孕妇也疯狂怀孕不是一件每天都要经历的事,它的发生会打乱我们的日常节奏会彻底改变我们的生活,还有可能对某些人,怀孕是一辈子只会经历一次的事情。你的身体内正在孕育另一个人,一个会让你终生牵挂的人一位妈妈和5岁小女孩的故事,却是很多妈妈的真实写照上周接诊一位33岁的宝妈带着5岁的小女儿,她们的故事普普通通,确是很多家长的真实写照。家长进门诊一坐着就开始自述孩子才5岁就得了过敏性鼻炎,检查腺样体肥大34,跑了几个医院吃了一堆EVE正在上演冰火两重天,端游大佬为何在手游中被萌新暴揍?这两年,越来越多曾经的老端游开始转战手游平台,这对于不少弃坑的玩家来说是一个很不错的回归机会。而老玩家们依靠曾经在端游中获得的游戏经验,来到手游里自然是如鱼得水,甚至能非常快速地统三家分晋独一份的王国裂变历史上常把三家分晋作为春秋战国的分界线,但是我们纵观整个春秋战国史,如此裂变立国的的貌似独此一份,这究竟为什么呢?今天我们就一起聊聊三家分晋的话题。首先第一个问题同为东周,为什么又新手第一次玩剧本杀如何避免尴尬剧本杀游戏中玩家经常会说一些游戏里的黑话,新手小白如何避免避免尴尬这边文章送给你,发车英文缩写篇MC不是rapper,是剧本杀的主持人。BP战斗点数,在某些剧本中,发生战斗的时候需
去甘南这么走最合理,纯干货拿走不谢或许当你去了甘南就会明白,真正的伊甸园,永远在我们自己的内心深处。无论世界如何变幻,按照自己的节奏生活,不急不缓,一样可以走向未来。一场治愈,一次重生,愿我们能在神秘的香巴拉之域,第二届黑河寒区试车节穿越黑河城市巡游活动启动共同感受驰骋中的激情速度活力,共游冰雪中浪漫与诗意的黑河。1月9日上午9时,第二届黑河寒区试车节穿越黑河城市巡游活动启动仪式在大黑河岛在水一方广场举行。第二届黑河寒区试车节穿越黑河我的驴行日记鲁山响马河2016年8月30日,我发的鲁山响马河采摘野生猕猴桃的帖子。由于上周商量好了,要去鲁山采摘,我问过张师傅后,就发了响马河的线路。早上6点出发,人数10人。本来出远门是要控制人数的,冬天的瓦屋山满足你所有的幻想雪到哪里,欢乐就到哪里2022年瓦屋山冰雪嘉年华正在火热进行中了瓦屋山这个宝藏雪境了解一下!一到1月耍雪季就稳占冬季玩雪亲子遛娃地头牌,刷爆各大平台的爆款3h车程就能抵达的冰雪世界三亚住宿怎么选,哪些酒店值得入住?出门在外旅行,如果能遇到一个舒适的住宿环境,整个行程便成功了一半了!入住在哪个区?三亚的酒店基本汇集在市区和四大海湾。市区内的住宿酒店相比较四大海湾的稍微便宜一点,因此如果你最在意拉萨布达拉宫八廓街1日游布达拉宫布达拉宫位于中国西藏自治区首府拉萨市区西北的玛布日山上,是一座宫堡式建筑群,一说为吐蕃王朝赞普干布为迎娶尺尊公主和公主而兴建1724另一说为,作为干布迁都拉萨后的王宫而建。贵州六盘水水光潋滟生态美央广网六盘水1月10日消息(见习记者栾小琳通讯员赵桦)日前,位于贵州省六盘水市中心城区的凤池园水光潋滟,风景如画,市民们纷纷出门享受难得的冬日暖阳。近年来,六盘水市不断优化城市空间八市边热门电视剧取景地,多少次来厦门就为这口沙茶面,汤香味浓从今天起记录我的2023旅游恢复啦,厦门再次成为热门出行地。这个沿海城市,虽然面积不大,但却有着山海美景,以及数不清的饕餮小吃。来厦门,必须要去鼓浪屿走走逛逛,这个非遗小岛适合慢步金领冠口味清淡还是飞鹤清淡,它们甜不甜?哪一款口味更清淡?近日,有读者想要了解金领冠和飞鹤奶粉的口味问题,来留言咨询金领冠口味清淡还是飞鹤清淡?今日,我们就来谈谈奶粉的甜度问题。其实,普通婴幼儿奶粉中,不少成分自身都是有一定甜度的。以金领冬天茄子吃腻了?教你新做法,不炒不炖不油炸,上桌比红烧肉还香冬天茄子吃腻了?教你新做法,不炒不炖不油炸,上桌比红烧肉还香。茄子,江浙人称为六蔬,广东人称为矮瓜,是一道非常不错的家常食材,颜色多为紫色或紫黑色,也有淡绿色或白色品种,根据品种的百度CTO王海峰AI发展进入深度学习阶段封面新闻记者付文超1月10日,百度CreateAI开发者大会举办。百度首席技术官王海峰表示,当前规模化的AI大生产已然形成,深度学习从技术生态产业等多个维度逐渐成熟,人工智能的技术