欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

SpringBoot整合Springfox-Swagger2

程序员文章站 2022-03-25 18:05:39
前言 不管Spring Boot整合还是SpringMVC整合Swagger都基本类似,重点就在于配置Swagger,它的精髓所在就在于配置。 @[toc] 1、Swagger简介 目前互联网时代前后端分离已成趋势,前后端混在一起,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发。解 ......

前言

不管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的界面,如下;
SpringBoot整合Springfox-Swagger2

4、配置swagger

不管是spring boot整合还是springmvc整合swagger都基本类似,重点就在于配置swagger,它的精髓所在就在于配置,这很关键。我们从下图来全局看看swagger的四部分重点布局:
SpringBoot整合Springfox-Swagger2

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、分析

SpringBoot整合Springfox-Swagger2

2、requesthandlerselectors过滤

点进requesthandlerselectors源码,分析如下:
SpringBoot整合Springfox-Swagger2

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包下。,这里只列出一些常用的注解,如下:
SpringBoot整合Springfox-Swagger2
如果要详细了解这些注解可以参考swagger2 注解说明

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

请求接口列表:在组范围内,只要被swagger2扫描匹配到的请求都会在这里出现。使用注解能更好的提高阅读性。
SpringBoot整合Springfox-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();
 }

效果如下:
SpringBoot整合Springfox-Swagger2
本篇文章非常浅显,若有不正之处,欢迎批评指正,感激不尽!

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

SpringBoot整合Springfox-Swagger2
参考:https://mp.weixin.qq.com/s/0-c0magtyoekx6qzmdug0w