前后端接口测试神器Swagger基本使用

养成习惯,先赞后看!!!

1. 前言

相信大家都了解过前端与后端的概念,所以就要说一下开发的模式了,主要是分为两类.

• 前后端不分离

  • 其实目前大部分的公司应该还是用的前后端不分离的技术,在这样的情况下后端开发人员的压力就比较大,因为就要考虑数据传输的方式以及接受参数等等情况,所以就比较难受,其实相信大家在工作或者是自己开发一些好玩的东西的时候会发现前端页面的编写和后台的逻辑代码其实相对来说是好写的,难就难在数据传输这一方面,自己当初用layui和SSM写一个小系统的时候,一直烦的就是前后端的数据怎么进行传输和共享.

  • 其次就是本身系统的耦合度就会比较高,因为前段编写的参数这些肯定是与后台的逻辑是一一绑定的,所以如果对系统进行优化升级的话,那么很明显就会出现牵一发而动全身的效果,前端数据一改,后端的代码相应的也会发生改变.也是变相的增加了开发的难度.

• 前后端分离

  有了上面这些冲突之后,就相应的诞生了前后端分离的技术,这项技术极大地降低了前后端数据交互方面的难度. 意思就是怎么传这个概念已经解决了 ,但是同时又带来了一个新的技术难点.虽然后端人员不用再管数据是如何进行传输的了.但是我们还是要规定需要传输和接收什么样的数据吧.简而言之就是 传什么 没有得到统一举个例子大家就懂了.

  在前后端分离模式中,后端人员只需要提供接口给前端人员调用就行了,但是前端人员总应该知道你的接口长什么样,需要哪些参数,你返回给我的是什么样的参数吧.
  于是在这样的需求下,就诞生了第一种解决方案—WORD文档,是的你没有看错,就是通过word文档,后端开发人员将整个的接口文档编写好之后发给前端开发人员,这如果是在开发规模不大或者说人员开发 数量比较少的情况下还是比较适用的,但是一旦开发人员规模增加起来,规模扩散开来,那么显然这种方式显然是不适用的.主要就是以下这些原因:

  • 文档越写越多,查看也不方便

    你想想一个前端开发看两三个人写的文档还是可以接受的,但是十几个,二十几个,那么显然就超过了他的承受范围.

  • 文档更新不及时

    就算你想看,但是后端开发人员没有及时的更新接口文档,那么你也是白搭.

  • 编写的过程中信息有误

    只要是人工操作,就免不了的会出现纰漏,比如说像什么变量名写错这种都是很正常的,但是这种错误排查起来却又十分的浪费时间.

  • 传来传去,浪费时间和流量

    本身文档这种东西传来传去就浪费时间,下载也浪费时间

  这时候终于到我们的主角上场了,Swagger就应运而生了,他帮助我们完美的解决了上述的问题.

  • 直接在项目中就可以编写文档
  • 不用手动传输文件,可以直接通过URL访问
  • 还能在线对接口进行测试,相当于变相丢弃使用postman
  • 更新及时
  • 机器自动生成,不要担心变量名写错等问题

  说了这么多了,我们就需要通过代码来实际展示一下效果了.

2. Springboot集成Swagger

新建一个Springboot-web项目

导入相关的依赖

<!--        Swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

编写一个简单的hello程序

@RestController
public class HelloController {
    
    
    @PostMapping(value = "/hello")
    public String hello(){
    
    
        return "hello";
    }
}

配置Swagger

@Configuration
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    
    
}

这样我们的Swagger基本就能够直接使用了,我们运行一下看看效果是什么样的.

目前我们看到的主要就是两部分,一个就是接口文档的大体信息.另一个就是我们所看到的接口信息.

我们首先来看一下为什么访问页面是swagger-ui.html文件,我们通过分析Swagger-ui文件的层级结构就能发现,如下图:

当然只要我们修改该文件的文件名,相应的访问路径也就发生改变了.

3. 接口文档个性化定制

我们来将文档大体描述信息修改我们个性化的样子.

这就需要我们在SwaggerConfig里面进行配置了.

这里我们主要是通过注入Docket这个对象来实现.

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

这里我们需要通过看源码来查看Docket应该怎么来编写.

看到他的构造函数之后我们就需要再次去理解一下 DocumentationType 是什么,继续查看源码

这里我们可以看到这三个对象的不同主要就是版本信息的不同.我们一般是选用 SWAGGER_2,之后我们就可以通过定义它的 apiInfo 属性来实现文档的个性化定制,我们同样继续查看 apiInfo 对象的源码,来看看apiInfo里面都能进行哪些配置

这里我们加上这些属性之后再来看看效果

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

    private ApiInfo apiInfo(){
    
    
        Contact contact=new Contact("瓤瓤","https://blog.csdn.net/lovely__RR","[email protected]");
        return new ApiInfo(
                "瓤瓤",
                "你我山巅自相逢,予你与我遇清风",
                "1.0",
                "https://blog.csdn.net/lovely__RR",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }

4. 自定义接口展示

主要就是定义我们想要展示那些接口给前端人员进行测试使用.

基本的语句就是

Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
    //这里面定义我们的扫描规则
                .build();

我们的扫描规则有两种

• 通过api接口进行配置

  这种主要有下面几种方式

  Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
  //配置接口扫描方式
  //basePackage:指定要扫描的包              //.apis(RequestHandlerSelectors.basePackage("com.rang.swaggerdemo.controller"))
  //这里我们也可以通过splitor关键字来实现同时扫描多个包 
  //.apis(RequestHandlerSelectors.basePackage("com.rang.swaggerdemo.controller"+splitor+"com.rang.test.controller"))
  //扫描全部
  //.apis(RequestHandlerSelectors.any())
  //不扫描
  //.apis(RequestHandlerSelectors.none())
  //扫描类上的注解,参数是一个注解的反射对象              //.apis(RequestHandlerSelectors.withClassAnnotation(Configuration.class))
  //扫描方法上的注解,参数是一个注解的反射对象             //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))             
                  .build();
  

  我们就来测试一下.apis(RequestHandlerSelectors.basePackage(“com.rang.swaggerdemo.controller”))

  效果

这样便会显示com.rang.swaggerdemo.controller包下面所有的接口

• 通过path路径即url地址栏进行配置

  这个主要就是通过url地址栏来进行

  主要也是下面这几种方式:

  Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
  //直接根据url地址栏进行匹配
  //.paths(PathSelectors.ant("/user/**"))
  //将任何借口都匹配进来等同于上述apis的any方法
  //.paths(PathSelectors.any())
  //不匹配任何借口等同于上述apis的none方法
  //.paths(PathSelectors.none())
  //根据正则表达式进行匹配
  //.paths(PathSelectors.regex(""))
                  .build();
  

  这里我们还是测试一下.paths(PathSelectors.ant("/user/**"))

  效果:

但是大家其实可以看到我们上面是有 /user/test 与 /user/getname 这两个方法,按道理这两个方法都应该出现的,但是我自己测试过之后发现,无论怎么实现,他都是只能匹配出最开的那一个,之后的就匹配不出来了.有知

5. 常用的注解

这里主要就是下面这几个注解

• @ApiModel

  这个注解主要是标注在实体类上面

  @ApiModel("用户实体类")//默认填充的是value字段
  public class User {
        
        
  }
  

• @ApiModelProperty

  这个注解主要是标注在实体类的属性上面

  @ApiModel("用户实体类")
  public class User {
        
        
      @ApiModelProperty("用户名")//默认填充的是value字段
      private String username;
      @ApiModelProperty("密码")
      private String password;
  }
  

  效果

• @Api

  这个注解主要是标注在controller上面

  @RestController
  @Api(tags = "测试的controller")//默认填充的是value字段,所以我们需要加上tags字段的名称
  public class HelloController {
        
        
    
  }
  

  这里要注意因为默认填充的都是value字段,但是本身@Api注解有点不同的就是它显示的内容应该是tags字段,所以添加的时候需要加上该字段

  效果

• @ApiOperation

  这个注解主要是标注在接口上面

  @RestController
  @Api(tags = "测试的controller")
  public class HelloController {
        
        
      
      @ApiOperation("用户测试")
      @PostMapping(value = "/user/test")
      public User user(){
        
        
          return new User();
      }
      
      @ApiOperation("获取用户的用户名")
      @PostMapping(value = "/uesr/getname")
      public String getname( User user){
        
        
          return user.getUsername();
      }
  }
  

• @ApiParam

  这个注解主要是标注在接口需要传入的参数上面

  @RestController
  @Api(tags = "测试的controller")
  public class HelloController {
        
        
      @PostMapping(value = "/hello")
      public String hello(@ApiParam("名字") String name){
        
        
          return "hello"+name;
      }
  
      @ApiOperation("用户测试")
      @PostMapping(value = "/user/test")
      public User user(){
        
        
          return new User();
      }
  
      @ApiOperation("获取用户的用户名")
      @PostMapping(value = "/uesr/getname")
      public String getname( User user){
        
        
          return user.getUsername();
      }
  }
  

  效果

6. 配置多个分组

当有多个开发人员的时候我们就能够通过配置多个分组来实现接口文档的整体一致性.

这里我们主要是通过注入多个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("小李");
    }

效果

这样也能够方便我们能够快速的查找到相应开发人员开发的接口,同时也能够查看每个人的开发进度,防止组员摸鱼.

7. 在线测试

其实说实话,有了这个功能,postman工具你基本上也用不到了,可以网页直接测试,又何必再开一个单独的软件来进行呢?

这里的操作过程其实就和之前我们接触过的接口测试工具是一样的,操作也是十分的简单,也能支持比较多的参数格式,既能支持form表单数据测试,也能支持json数据的测试

效果

都看到这儿了,如果觉得对你有帮助的话,希望你能关注我的公众号,新人博主需要你的支持.