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

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接口的描述内容、如何自主决定某些内容的显示与隐藏等相关的内容,这里就给大家分享到这里啦。关于本篇内容你有什么自己的想法或独到见解么?

你在Steam上买的第一款游戏是什么?感觉如何?我个人在steam玩的第一款游戏是巫师3狂猎,在没有入手正版之前我一直玩的都是某站的盗版。直到有一次我听说了游戏开发商波兰蠢驴的故事,便义无反顾的入了正。波兰蠢驴这个游戏公司真的是在王者荣耀中,为什么天美每次把英雄削废之后,不是增强而是重做?大家好,我是袁妈,爱王者,爱生活。熟悉峡谷最新动态,掌握各英雄技能属性。今天重点介绍英雄削弱与重做问题。王者荣耀英雄变动问题这款手游自两年半上线以来,从未停止更新的步伐。新英雄在不王者荣耀排位除了55开黑,单排怎样尽可能屏蔽坑货队友?目前的王者荣耀有个坑爹的设定,就是匹配机制问题,在匹配和赏金中你会发现队友段位参差不齐大到荣耀王者小到黄金,那么这局你们输定了,开局直接被对面碾压,几分钟你们就该投降了。你也许说两你身边癌症患者都是怎么发现得癌的?2014年4月初我父亲吃了一块腊鸭,由于牙齿不好不小心把一块小骨头也吞下去了,之后就感觉胃部不舒服,次日去上厕所时发现大便带血,就猜想前一天吃下的骨头可能刺伤了胃流血了,于是去了人招聘时发现应聘者的能力全方面凌驾于自己之上是怎样一种体验?谢谢你的邀请问题我来回答你所提的问题,首先你要具备些低调做人,高调做事的做人道理。如果招聘时发现应聘者的能力那只能说明你比较幸运的体验,那你应聘后,环境还需要你慢慢的适应。全心全意是深圳户口好还是农村户口好?为什么?是深圳户口好还是农村户口好?那得看您怎么衡量了,都各有好处,看哪个好处适合您。如果您是长期在深圳工作的话,又想带孩子在身边又能让孩子受到好一点的教育,可以考虑上深圳户口,因为深圳户农村合作医疗80岁以上不用交了是真的吗?农村合作医疗是国家给农村居民办理的一份社会保障,在农村实施已经十八年,由原来的每人缴费10元,逐年增涨,现在我们这里已经涨到320元,对于农村合作医疗费的增涨引起了农村很多家庭的怨一个四十岁的大学教授失业了,该何去何从?大学教授会失业吗?在高校工作十几年了,还没见过一个教授失业的。在大学里,除了部分外籍专家是实行年薪制不入编外,绝大多数教授都是事业编制人员。学校是不能轻易解除事业编制人员人事关系的有谁听过或见过真正的武林高手?前些年拆迁,因补偿太低,好几户居民拒绝搬离。开发商老李大为恼火,便让他小舅子大金牙处理此事,一定要在最短期限内把那几户人家赶走。大金牙姓张,秃头,长的五大三粗,身上刺满了花纹。因为邻居蹭我家网,说了怕被骂,关了怕报复,我该怎么办?谢谢邀请!提这种问题的人,我觉得你太小气了!你怎么知道邻居蹭你网?记住了远亲都不如近邻!心胸开阔一点!从你提这种问题,我保证你在社会上寸步难行!你应该与人为善!千万别小肚鸡肠!行了死刑犯在监狱要不要干活?如果要干活是带着脚镣去吗?首先要明确的是,死刑犯不进监狱,而是关押在看守所里面的,看守所跟监狱其实是有区别的,监狱是中长期死缓等犯人关押的地方,看守所是短期犯人加上没有判刑的犯人以及普通拘押的犯人跟死刑犯呆
孙莉18岁就跟了黄磊,三胎生了儿子后,她为何又选择复出?早年间,被问到害不害怕黄磊和女大学生产生感情的时候,孙莉自信地回答不会啊,因为她们都不如我。那时的孙莉清丽无双才华横溢,黄磊对她一见钟情而体贴备至,所以她笃信自己对伴侣的吸引力。如埃及法老著名实验把婴儿聚一起,不教说话,会产生新的语言吗?自古以来,都有一个非常深奥的问题困扰着人类语言,究竟是如何产生的?早在6世纪,就有一位埃及法老做了一个极为著名的实验将婴儿聚集在一起,不教说话,来看看语言究竟是否能够产生。语言的奥倪萍儿子虎子病痛时被父亲抛弃留阴影,母亲再婚继父治愈他一生2017年,倪萍手捧鲜花登上了朗读者节目,为大家讲述了自己这十几年的心酸历程。倪萍与1999年生下了儿子虎子,可被检查出患有先天性眼疾,倪萍便一个人带着虎子走上了10年的漫长求医之姑娘大意了,镜片里的反射早就被大家看得一清二楚,不觉得尴尬吗看不见我看不见我看不见我女朋友给做的大家看应该注意点什么??你属于哪一种呢?有这样的男朋友大家看还有必要继续吗?有车他不开非要自己扛着这个狗吹一辈子了不提雪怎么写雪很大??心情瞬间2019年,宁夏男子瘫痪6年后,妻子不堪重负离婚,7岁女儿含泪照顾前言2019年,记者来到宁夏银川解放军第五医院某科室病房外,看到一个头发凌乱面黄肌瘦,身材瘦弱的小女孩,正端着一盆刚打来的热水,准备给病床上的父亲擦拭身体,在医护人员的介绍下,记者2019年缅甸姑娘嫁湖北农村小伙,生双胞胎后,整日流泪念叨一句话在我国境内,有着为数不少来工作的外国人。有些是对中国的历史文化感到好奇,希望在工作和生活中了解到更多知识有些则是周边国家的人民,他们来到中国,希望能够找到比家乡更好的工作,甚至希望没钱还是没技术?琼州海峡仅19公里宽,为何不建座跨海大桥?作为我国的第二大海岛,海南省一直与我国大陆隔着一道琼州海峡,也正是因为这道海峡的存在,使得海南省与大陆地区的经济文化交流长期存在阻碍。但是奇怪的是,作为基建狂魔的我国,这么多年都没将于6月1日首发全新雷克萨斯RX尾部预告图太平洋汽车网新车频道近日,我们从社交媒体获得了雷克萨斯RX(询底价查参配)的尾部预告图,并表示其将于6月1日全球首发。结合此前的信息来看,新车在外观及内饰方面采用全新的设计理念,仍大连82岁老人在孙子结婚当天留千字遗书后又身系红腰带从12楼跳下一对新人结婚当天,82岁的奶奶系上红腰带从12楼一跃而下,留下一封千字遗书张贴在居民楼门口整整六页,依稀可以看出遗书中写道王涛狼心狗肺,不得好死,天打雷劈,能宗莲胡说八道,烂舌头,形势确定,广东将从水煮转为桑拿!分析大范围中暑天气真要来了在过去的一段时间里,华南沿海暴雨频频,已然成为我国的暴雨中心像是5月1日5月28日的全国降水量分布图上看,5月1日以来,我国南方地区江南华南多地降雨量达到200300毫米,尤其是湖神舟十四号载人飞船,就位据中国载人航天工程办公室消息,北京时间2022年5月29日,神舟十四号载人飞船与长征二号F遥十四运载火箭组合体已转运至发射区。目前,发射场设施设备状态良好,后续将按计划开展发射前的