前言

不管Spring Boot整合还是SpringMVC整合Swagger都基本类似,重点就在于配置Swagger,它的精髓所在就在于配置。

@

1、Swagger简介

目前互联网时代前后端分离已成趋势,前后端混在一起,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发。解决方案就是前后端通过API进行交互达到相对独立且松耦合。Swagger就是这样的一个API框架,Swagger支持多种语言 如:JavaPHP等,它号称是世界上最流行的API框架!

2、整合前可能遇到的问题

1、

导入好依赖jar包之后,使用注解说找不到之类的问题,如遇到,请参考:所有Intellij IDEA Cannot Resolve Symbol XXX问题的解决方法汇总

2、

版本问题,SpringBoot的版本很多,被集成的框架版本也很多,可能版本高一点或者低一点就可能出现各种bug,这是集成其他框架的通病,这里得注意一下。如果运行出现一些什么bug,如果对SpringBoot底层原理不是很了解的可以先百度谷歌一下,找不到建议不妨换个SpringBoot的版本

3、SpringBoot集成Swagger

注意:jdk 1.8以上才能运行swagger2

1、

导入两个jar包依赖

<!-- 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>

2、

要想使用Swagger,必须编写一个配置类来配置 Swagger,这里的配置类如下

@Configuration //说明这是一个配置类
@EnableSwagger2// 该注解开启Swagger2的自动配置
public class SwaggerConfig { //随便的一个类名 }

3、

这个时候已经算是初步整合完毕了,启动项目可访问http://localhost:8080/swagger-ui.html 可以看到swagger的界面,如下;

4、配置Swagger

不管是Spring Boot整合还是SpringMVC整合Swagger都基本类似,重点就在于配置Swagger,它的精髓所在就在于配置,这很关键。我们从下图来全局看看Swagger的四部分重点布局:

4.1、Swagger四部分布局

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

第一部分--API分组:如果没有配置分组默认是default。通过Swagger实例Docket的groupName()方法即可配置分组

第二部分--基本描述:可以通过Swagger实例Docket的apiInfo()方法中的ApiInfo实例参数配置文档信息

第三部分--请求接口列表:在组范围内,只要被Swagger2扫描匹配到的请求都会在这里出现。

第四部分--实体列表:只要实体在请求接口的返回值上(即使是泛型),都能映射到实体项中!

第四部分注意:并不是因为@ApiModel注解让实体显示在Models列表里,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。前者为类添加注释,后者为类属性添加注释。

4.2、第二部分:API基本信息

先从第二部分开始分析,这样分析对理解第一部分比较有帮助。

@Configuration
@EnableSwagger2
@ComponentScan("com.yichun.swagger_boot_demo.controller")
public class SwaggerConfig {
@Bean
public Docket docker(){
// 构造函数传入初始化规范,这是swagger2规范
return new Docket(DocumentationType.SWAGGER_2)
//apiInfo: 添加api详情信息,参数为ApiInfo类型的参数,这个参数包含了第二部分的所有信息比如标题、描述、版本之类的,开发中一般都会自定义这些信息
.apiInfo(apiInfo())
.groupName("yichun123")
//配置是否启用Swagger,如果是false,在浏览器将无法访问,默认是true
.enable(true)
.select()
//apis: 添加过滤条件,
.apis(RequestHandlerSelectors.basePackage("com.yichun.swagger_boot_demo.controller"))
//paths: 这里是控制哪些路径的api会被显示出来,比如下方的参数就是除了/user以外的其它路径都会生成api文档
.paths((String a) ->
!a.equals("/user"))
.build();
} private ApiInfo apiInfo(){
Contact contact = new Contact("名字:name", "个人链接:http://xxx.xxx.com/", "邮箱:XXX");
return new ApiInfo(
"标题内容", // 标题
"描述内容", // 描述
"版本内容:v1.0", // 版本
"链接:http://terms.service.url/", // 组织链接
contact, // 联系人信息
"许可:Apach 2.0 ", // 许可
"许可链接:XXX", // 许可连接
new ArrayList<>()// 扩展
);
}
}
1、分析

2、RequestHandlerSelectors过滤

点进RequestHandlerSelectors源码,分析如下:

4.3、第一部分:配置API分组

实际上,上面的内容就是一个完整的API组

1、配置一个分组

我们之前说过,如果没有配置分组默认是default。通过Swagger实例Docket的groupName()方法即可配置分组,代码如下:

@Bean
public Docket docket2(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 配置基本API信息
.groupName("hello") // 配置分组
// 省略配置....
}

2、如何配置多个分组

很简单,配置多个分组只需要配置多个docket即可,代码如下:

@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("组一")
// 省略配置....
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("组二")
// 省略配置....
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("组三")
// 省略配置....
}

4.4、Swagger2的常用注解

讲第三部分和第四部分前,非常有必要先了解swagger2的常用注解,用注解的话,可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读!这点也是swagger2的重中之重!

首先我们得知道一点Swagger的所有注解定义在io.swagger.annotations包下。,这里只列出一些常用的注解,如下:



如果要详细了解这些注解可以参考swagger2 注解说明

4.5、第三部分:API请求列表

请求接口列表:在组范围内,只要被Swagger2扫描匹配到的请求都会在这里出现。使用注解能更好的提高阅读性。

4.6、第四部分:API实体列表

之前说过,只要实体在请求接口的返回值上(即使是泛型),都能映射到实体项中!是的,因此我们第一步是先有实体类。

1、

我们先随便创建一个实体类

@ApiModel("用户实体类")
public class User { @ApiModelProperty("性别")
public String sex; @ApiModelProperty(value ="用户名",allowableValues = "11,12")
public int name;
}

当然@ApiModelProperty注解里有很多属性,也会有许多坑,这里注意一下,本篇文章暂不概述。

2、

只要这个实体在请求接口的返回值上(包括泛型),都能映射到实体项中,所以我们编写代码如下:

 @GetMapping("/User2")
public User getUser2(){ return new User();
}

效果如下:



本篇文章非常浅显,若有不正之处,欢迎批评指正,感激不尽!

欢迎各位关注我的公众号,里面有一些java学习资料和一大波java电子书籍,比如说周志明老师的深入java虚拟机、java编程思想、核心技术卷、大话设计模式、java并发编程实战.....都是java的圣经,不说了快上Tomcat车,咋们走!最主要的是一起探讨技术,向往技术,追求技术,说好了来了就是盆友喔...



参考:https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w

SpringBoot整合Springfox-Swagger2的更多相关文章

  1. SpringBoot整合Swagger2,再也不用维护接口文档了!

    前后端分离后,维护接口文档基本上是必不可少的工作.一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却很 ...

  2. SpringBoot整合系列-整合Swagger2

    原创作品,可以转载,但是请标注出处地址:https://www.cnblogs.com/V1haoge/p/9959844.html SpringBoot整合Swagger2 步骤 第一步:添加必要的 ...

  3. SpringBoot整合Swagger2

    相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档. 手写Api文档的几个痛点: 文档需 ...

  4. SpringBoot学习笔记(16)----SpringBoot整合Swagger2

    Swagger 是一个规范和完整的框架,用于生成,描述,调用和可视化RESTful风格的web服务 http://swagger.io Springfox的前身是swagger-springmvc,是 ...

  5. Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

    前后端分离后,维护接口文档基本上是必不可少的工作. 一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却 ...

  6. SpringBoot整合Swagger2(Demo示例)

    写在前面 由于公司项目采用前后端分离,维护接口文档基本上是必不可少的工作.一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理 ...

  7. springboot 整合Swagger2的使用

    Swagger2相较于传统Api文档的优点 手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时. 接口返回结果不明确 不能直接在线测试接口,通常需要使用工 ...

  8. SpringBoot整合Swagger2案例,以及报错:java.lang.NumberFormatException: For input string: ""原因和解决办法

    原文链接:https://blog.csdn.net/weixin_43724369/article/details/89341949 SpringBoot整合Swagger2案例 先说SpringB ...

  9. SpringBoot整合Swagger2详细教程

    1. 简介   随着前后端分离开发模式越来越流行,编写接口文档变成了开发人员非常头疼的事.而Swagger是一个规范且完整的web框架,用于生成.描述.调用可视化的RESTful风格的在线接口文档,并 ...

  10. SpringBoot整合Swagger2及使用

    简介 swagger是一个流行的API开发框架,这个框架以"开放API声明"(OpenAPI Specification,OAS)为基础, 对整个API的开发周期都提供了相应的解决 ...

随机推荐

  1. ABP开发框架前后端开发系列---(16)ABP框架升级最新版本的经验总结

    有一小段时间没有持续升级ABP框架了,最近就因应客户的需要,把ABP框架进行全面的更新,由于我们应用的ABP框架,基础部分还是会使用官方的内容,因此升级的时候需要把官方基础ABP的DLL进行全面的更新 ...

  2. 从0开始搭建一个阿里云java部署环境

    一.购买服务器 https://www.aliyun.com/daily-act/ecs/activity_selection?spm=5176.8112568.738194.8.674c9ed53Y ...

  3. 网络编程概念 和OSI七层结构简介

    什么是网络编程 网络通常指的是计算机中的互联网,是由多台计算机通过网线或其他媒介相互链接组成的 编写基于网络的应用程序的过程序称之为网络编程 学习网络编程就是要学习利用网络来与另一台计算机相互传输数据 ...

  4. 数据挖掘入门系列教程(三)之scikit-learn框架基本使用(以K近邻算法为例)

    数据挖掘入门系列教程(三)之scikit-learn框架基本使用(以K近邻算法为例) 简介 scikit-learn 估计器 加载数据集 进行fit训练 设置参数 预处理 流水线 结尾 数据挖掘入门系 ...

  5. Apache Tomcat 文件包含漏洞(CVE-2020-1938)

    2月20日,国家信息安全漏洞共享平台(CNVD)发布了Apache Tomcat文件包含漏洞(CNVD-2020-10487/CVE-2020-1938).该漏洞是由于Tomcat AJP协议存在缺陷 ...

  6. go学习第五天、运算符

    算术运算符 下表列出了所有Go语言的算术运算符.假定 A 值为 10,B 值为 20 运算符 描述 实例 + 相加 A + B 输出结果 30 - 相减 A - B 输出结果 -10 * 相乘 A * ...

  7. 常用计算机CMD 命令

      cd\  '返回到根目录  cd..  '返回到上一级目录 1 cd 显示当前目录名或改变当前目录. 2 dir 显示目录中的文件和子目录列表.  3 md 创建一个目录.  4 mkdir  创 ...

  8. 【Weiss】【第03章】练习3.20:中缀表达式转后缀表达式

    [练习3.20] a.编写一个程序将中缀表达式转换为后缀表达式,该中缀表达式含括号及四则运算. b.把幂操作符添加到你的指令系统中去. c.编写一个程序将后缀表达式转化为中缀表达式. Answer: ...

  9. Lambda表达式学习笔记

    Lambda基础语法 Java8中引入了一个新的操作符" -> ",该操作符被称为箭头操作符或Lambda操作符,箭头操作符将Lambda表达式拆分成两部分: 左侧:Lamb ...

  10. 计算广告中的CPM和eCPM

    计算广告中的CPM和eCPM CPM和eCPM分别是什么? CPM(Cost per Mille ) : 千次展示付费.是针对广告主说的,你要花多少钱,购买一千次广告展示的机会.类似的还有CPC (C ...