Swagger初见

作者: ML李嘉图


目录

  • [Swagger简介]
  • [SpringBoot集成Swagger]
  • [配置Swagger]
  • [配置扫描接口]
  • [配置Swagger开关]
  • [配置API分组]
  • [实体配置]
  • [常用注解]


Swagger简介

前后端分离

  • 前端 -> 前端控制层、视图层
  • 后端 -> 后端控制层、服务层、数据访问层
  • 前后端通过API进行交互
  • 前后端相对独立且松耦合 产生的问题
  • 前后端集成,前端或者后端无法做到"及时协商,尽早解决”,最终导致问题集中爆发 解决方案
  • 首先定义schema [ 计划的提纲 ],并实时跟踪最新的API,降低集成风险 Swagger
  • 号称世界上最流行的API框架
  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  • 直接运行,在线测试API
  • 支持多种语言 (如:Java,PHP等)
  • 官网:https://swagger.io/

SpringBoot集成Swagger

SpringBoot集成Swagger => springfox,两个jar包

  • Springfox-swagger2
  • swagger-springmvc 使用Swagger

要求:jdk 1.8 + 否则swagger2无法运行

步骤: 1、新建一个SpringBoot-web项目 2、添加Maven依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

3、编写HelloController,测试确保运行成功! 4、要使用Swagger,们需要编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

5、访问测试 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面;

配置Swagger

1、Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger。

@Bean //配置docket以配置Swagger具体参数public Docket docket() {   return new Docket(DocumentationType.SWAGGER_2);}

2、可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

3、Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4、重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果;

配置扫描接口

1、构建Docket时通过select()方法配置怎么扫描接口。

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
      .build();
}

2、重启项目测试,由于们配置根据包的路径扫描接口,所以们只能看到一个类 3、除了通过包路径配置扫描接口外,还可以通过配置其他方式扫描接口,这里注释一下所有的配置方式:

any() // 扫描所有,项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

4、除此之外,们还可以配置接口扫描过滤:

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

5、这里的可选值还有

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

配置Swagger开关

1、通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
      .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

2、如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean b = environment.acceptsProfiles(of);

   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
      .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

3、可以在项目中增加一个dev的配置文件查看效果!

配置API分组

1、如果没有配置分组,默认是default。通过groupName()方法即可配置分组:

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

2、重启项目查看分组 3、如何配置多个分组?配置多个分组只需要配置多个docket即可:

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

实体配置

1、新建一个实体类

@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

2、只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中:

@RequestMapping("/getUser")
public User getUser(){
   return new User();
}

3、重启查看测试

注:并不是因为@ApiModel这个注解让实体显示在这里了,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。 @ApiModel为类添加注释 @ApiModelProperty为类属性添加注释

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的,未列举出来的可以另行查阅说明:

Swagger注解简单说明
@Api(tags = “xxx模块说明”)作用在模块类上
@ApiOperation(“xxx接口说明”)作用在接口方法上
@ApiModel(“xxxPOJO说明”)作用在模型类上:如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)作用在类方法和属性上,hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)作用在参数、方法和字段上,类似@ApiModelProperty

@ApiOperation(“李嘉图的接口”) @PostMapping(“/zwt”) @ResponseBody public String zwt(@ApiParam(“这个名字会被返回”)String username){ return username; }

这样的话,可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读!

相较于传统的Postman或Curl方式测试接口,使用swagger简直就是傻瓜式操作,不需要额外说明文档(写得好本身就是文档)而且更不容易出错,只需要录入数据然后点击Execute,如果再配合自动化框架,可以说基本就不需要人为操作了。
Swagger是个优秀的工具,现在国内已经有很多的中小型互联网公司都在使用它,相较于传统的要先出Word接口文档再测试的方式,显然这样也更符合现在的快速迭代开发行情。

当然了,提醒下大家在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运行时内存。  
> 原文创作:ML李嘉图
>
> 原文链接:https://www.cnblogs.com/zwtblog/p/15208139.html

## 文章列表
- [项目MyBlog](https://www.oomspot.com/post/xiangmumyblog)
- [阶段总结Java基础超进阶](https://www.oomspot.com/post/jieduanzongjiejavajichuchaojinjie)
- [链表题解](https://www.oomspot.com/post/lianbiaotijie)
- [郭德纲罗翔语录](https://www.oomspot.com/post/guodegangluoxiangyulu)
- [语录转载](https://www.oomspot.com/post/yuluzhuanzai)
- [设计模式更新中](https://www.oomspot.com/post/shejimoshigengxinzhong)
- [设计模式图解](https://www.oomspot.com/post/shejimoshitujie)
- [论坛项目](https://www.oomspot.com/post/luntanxiangmu)
- [计算机网络汇总](https://www.oomspot.com/post/jisuanjiwangluohuizong)
- [计算机网络TCP篇](https://www.oomspot.com/post/jisuanjiwangluotcppian)
- [计算机网络IP篇](https://www.oomspot.com/post/jisuanjiwangluoippian)
- [计算机网络HTTP篇](https://www.oomspot.com/post/jisuanjiwangluohttppian)
- [计算机组成原理图解](https://www.oomspot.com/post/jisuanjizuchengyuanlitujie)
- [计算机组成原理初见](https://www.oomspot.com/post/jisuanjizuchengyuanlichujian)
- [自定义starter](https://www.oomspot.com/post/zidingyistarter)
- [缓存穿透,击穿,雪崩详解](https://www.oomspot.com/post/huancunchuantoujichuanxuebengxiangjie)
- [笔试格式](https://www.oomspot.com/post/bishigeshi)
- [温故知新输入网址显示网页到底到底到底到底发生了什么?](https://www.oomspot.com/post/wenguzhixinshuruwangzhixianshiwangyedaodidaodidaod)
- [深度学习之神经网络的结构](https://www.oomspot.com/post/shenduxuexizhishenjingwangluodejiegou)
- [栈和队列题解方法](https://www.oomspot.com/post/zhanheduilietijiefangfa)
- [数组LeetCode笔试](https://www.oomspot.com/post/shuzuleetcodebishi)
- [数据结构](https://www.oomspot.com/post/shujujiegou)
- [数据库事故](https://www.oomspot.com/post/shujukushigu)
- [操作系统初见?见了好多次,次次都要学!](https://www.oomspot.com/post/caozuoxitongchujianjianlehaoduocicicidouyaoxue)
- [怎么通俗的理解Netty呢?](https://www.oomspot.com/post/zenmetongsudelijienettyni)
- [富文本编辑器SpringBoot](https://www.oomspot.com/post/fuwenbenbianjiqispringboot)
- [字符串题解方法](https://www.oomspot.com/post/zifuchuantijiefangfa)
- [基础算法学习](https://www.oomspot.com/post/jichusuanfaxuexi)
- [双指针题解](https://www.oomspot.com/post/shuangzhizhentijie)
- [刷题加油](https://www.oomspot.com/post/shuatijiayou)
- [分布式锁初见](https://www.oomspot.com/post/fenbushisuochujian)
- [互联网基础架构图解](https://www.oomspot.com/post/hulianwangjichujiagoutujie)
- [二叉树题解方法](https://www.oomspot.com/post/erchashutijiefangfa)
- [三体语录](https://www.oomspot.com/post/santiyulu)
- [Swagger初见](https://www.oomspot.com/post/swaggerchujian)
- [Spring初见](https://www.oomspot.com/post/springchujian)
- [SpringSecurity图解](https://www.oomspot.com/post/springsecuritytujie)
- [SpringSecurityShiro初见](https://www.oomspot.com/post/springsecurityshirochujian)
- [SpringBoot异步定时邮件任务](https://www.oomspot.com/post/springbootyibudingshiyoujianrenwu)
- [SpringBootWeb初见](https://www.oomspot.com/post/springbootwebchujian)
- [SprinBootSpringData整合](https://www.oomspot.com/post/sprinbootspringdatazhenghe)
- [SpingBootDubboZookeeper分布式](https://www.oomspot.com/post/spingbootdubbozookeeperfenbushi)
- [Shiro登陆流程认证图解](https://www.oomspot.com/post/shirodengluliuchengrenzhengtujie)
- [Redis数据类型应用场景](https://www.oomspot.com/post/redisshujuleixingyingyongchangjing)
- [Redis conf分析](https://www.oomspot.com/post/redisconffenxi)
- [Radius协议学习](https://www.oomspot.com/post/radiusxieyixuexi)
- [RabbitMQ进阶](https://www.oomspot.com/post/rabbitmqjinjie)
- [RabbitMQ初见](https://www.oomspot.com/post/rabbitmqchujian)
- [Netty初见三大组件简单使用](https://www.oomspot.com/post/nettychujiansandazujianjiandanshiyong)
- [MySql分区、分表和分库](https://www.oomspot.com/post/mysqlfenqufenbiaohefenku)
- [MySQL实战45讲2125笔记](https://www.oomspot.com/post/mysqlshizhan45jiang2125biji)
- [MySQL实战45讲1620笔记](https://www.oomspot.com/post/mysqlshizhan45jiang1620biji)
- [MySQL实战45讲1015笔记](https://www.oomspot.com/post/mysqlshizhan45jiang1015biji)
- [Linux实战常用命令](https://www.oomspot.com/post/linuxshizhanchangyongmingling)
- [Java爬虫小项目](https://www.oomspot.com/post/javapachongxiaoxiangmu)
- [JavaNIO](https://www.oomspot.com/post/javanio)
- [JVM调优命令](https://www.oomspot.com/post/jvmdiaoyoumingling)
- [JVM深入](https://www.oomspot.com/post/jvmshenru)
- [JVM初见](https://www.oomspot.com/post/jvmchujian)
- [JVM优化](https://www.oomspot.com/post/jvmyouhua)
- [JAVA中直接用Jdbc就能操作数据库了,为什么还要用spring框架?](https://www.oomspot.com/post/javazhongzhijieyongjdbcjiunengcaozuoshujukuleweish)
- [Hash题解方法](https://www.oomspot.com/post/hashtijiefangfa)
- [HashMap的转化时机](https://www.oomspot.com/post/hashmapdezhuanhuashiji)
- [HashMap源码分析](https://www.oomspot.com/post/hashmapyuanmafenxi)
- [Github博客园初见](https://www.oomspot.com/post/githubchujian)
- [GC优化案例](https://www.oomspot.com/post/gcyouhuaanli)
- [ElasticSearch7 X X初见模仿京东搜索的实战](https://www.oomspot.com/post/elasticsearch7xxchujianmofangjingdongsousuodeshizh)
- [Docker初见](https://www.oomspot.com/post/dockerchujian)
- [CI/CD企业级DevOps](https://www.oomspot.com/post/cicdqiyejidevops)

更多推荐

更多
  • Java开发常见错误100例-29数据和代码:数据就是数据,代码就是代码 29 数据和代码:数据就是数据,代码就是代码 今天,我来和你聊聊数据和代码的问题。 正如这一讲标题"数据就是数据方面的很多漏洞,都是源自把数据当成了代码来执行,也就是注入类问题,比如: 客户端提供给服务端的查询值,是一个数据,会
  • Java开发常见错误100例-33加餐3:定位应用问题,排错套路很重要 33 加餐3:定位应用问题,排错套路很重要 咱们这个课程已经更新 13 讲了,感谢各位同学一直在坚持学习,并在评论区留下了很多高质量,有的是分享自己曾经踩的坑,有的是对课后思考题的详细解答,还有的是提出了非常好的问题,进一步丰富了这
  • Java开发常见错误100例-36加餐6:这15年来,我是如何在工作中学习技术和英语的? 36 加餐6:这15年来,我是如何在工作中学习技术和英语的? 今天,我来和你聊聊如何在工作中,让自己成长得更快。 工作这些年来,经常会有同学来找我沟通学习和成长,他们的问题可以归结为沟通学习和成长,他们的问题可以归结为两个。 一
  • Java开发常见错误100例-16用好Java8的日期时间类,少踩一些“老三样”的坑 16 用好Java 8的日期时间类,少踩一些"老三样"的坑 今天,我来和你说说恼人的时间错乱问题。 在,使用 Date、Calender 和 SimpleDateFormat,来声明时间戳、使用日历处理日期和格式化解析日期时间。但
  • Java开发常见错误100例-答疑篇:代码篇思考题集锦(一) 答疑篇:代码篇思考题集锦(一)题的答案。因此呢,我特地将这个课程涉及的思考题进行了梳理,把其中的 67 个问题的答案或者说解题思路,详细地写了出来,并整理成了一个"答疑篇"模块。 我把这些问题拆分为了 6 篇分别更新,你可以根据自己的
  • Java开发常见错误100例-30如何正确保存和传输敏感数据? 30 如何正确保存和传输敏感数据? 今天,我们从安全角度来聊聊用户名、密码、身份证等敏的散列、对称加密和非对称加密算法,以及 HTTPS 等相关知识。 应该怎样保存用户密码? - 最敏感的数据恐怕就是用户的密
  • Java开发常见错误100例-15序列化:一来一回你还是原来的你吗? 15 序列化:一来一回你还是原来的你吗? 今天,我来和你聊聊序列化相关的坑和最佳实践。 序列化是把对象转换为字节流的过程,以方便传输或存储。反序列化,则是反过来把字节流转换为对象化,则是反过来把字节流转换为对象的过程。在介绍文件
  • Java开发常见错误100例-23缓存设计:缓存可以锦上添花也可以落井下石 23 缓存设计:缓存可以锦上添花也可以落井下石 今天,我从设计的角度,与你聊聊缓存。 通常我们会使用更快的介质(比如内存)作(比如磁盘)读取数据慢的问题,缓存是用空间换时间,来解决性能问题的一种架构设计模式。更重要的是,磁盘上存储
  • Java开发常见错误100例-17别以为“自动挡”就不可能出现OOM 17 别以为"自动挡"就不可能出现OOM 今天,我要和你分享的主题是,别以为"自动挡"就不可能出现 OOM。 这里的"自动挡",是我自动垃圾收集器的戏称。的确,经过这么多年的发展,Java 的垃圾收集器已经非常成熟了。有了自动垃圾
  • Java开发常见错误100例-结束语写代码时,如何才能尽量避免踩坑? 结束语 写代码时,如何才能尽量避免踩坑? -余时间都用了在这个课程的创作,以及回答你的问题上,很累很辛苦,但是看到你的认真学习和对课程内容的好评,看到你不仅收获了知识还燃起了钻研源码的热情,我也非常高兴,深觉一切的辛苦付出都是甜蜜的。
  • 近期文章

    更多
    文章目录

      推荐作者

      更多