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

萌萌哒的瓤瓤

发布于 2021-01-13 17:46:58

4.5K0

发布于 2021-01-13 17:46:58

文章被收录于专栏：java，python，数据结构，算法

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","2293557957@qq.com");
        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();

我们的扫描规则有两种

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

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

5. 常用的注解

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

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("小李");
    }

效果