走进Java接口测试之接口管理工具Swagger2

举报
zuozewei 发表于 2021/09/22 21:49:08 2021/09/22
【摘要】 本文主要是对Swagger的简单使用和Springboot集成进行了说明,详细的用法,可自行搜索相关资料下,这里就不阐述了。因为对于百分之八十之上的文档要求基本能满足了。最后,一定要在生产环境关闭Swagger,基于安全因素。

前言

现在都奉行前后端分离开发和微服务大行其道,前后端技术在各自道路上越走越远。
前后端唯一联系变成了API接口,API文档变成了前后端开发人员&测试人员联系的纽带。所以一款强大的Restful API文档就变得至关重要了。而目前在后端领域,基本上是Swagger的天下了。

Swagger2综述

Swagger是一款Restful 接口的文档在线自动生成、功能测试框架。一个规范和完整的框架,用于生成、描述、调用和可视化Restful 风格的Web服务,加上Swagger-UI,可以有很好的呈现。

Swagger是一组开源项目,其中主要项目如下:

  • Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
  • Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
  • Swagger-js: 用于JavaScript的Swagger实现。
  • Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。
  • Swagger-UI:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
  • Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。

Swagger-UI 是什么?

Swagger-UI 是一款Restful接口的文档在线自动生成+功能测试功能软件。
Swagger-UI 的官方地址:http://swagger.io/
Github上的项目地址:https://github.com/swagger-api/swagger-ui
官方提供的demo地址:http://petstore.swagger.io/
在这里插入图片描述

为什么API接口文档用Swagger-UI ?

现在多数的项目开发中,网站和移动端都需要进行数据交互和对接,这少不了使用Restful编写API接口这种场景。 特别是不同开发&测试团队协作时,就更需要以规范和文档作为标准和协作基础。良好的文档可以减少沟通成本,达到事半功倍的效果。
有时对一些API说明的理解比较模糊,总想着能直接验证一下自己的理解就好了,而不是需要去项目写测试代码来验证自己的想法。即API文档应具备直接执行能力,这种能力类似word,wiki等是无法提供。Swagger-UI 就是这样一种利器,基于Html+Javascript实现,倾向于在线文档和测试,使用和集成十分简单,能容易地生成不同模块下的API列表, 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。

Swagger-UI 怎么用?

目前官方提供的Swagger-UI 的使用方式主要有2种:

  • 与不同的服务端代码集成,在服务端代码中嵌入SwaggerUI文档生成代码,部署时自动生成。
  • 手动编辑对应的Json文档,该Json文档有其特定格式,相对比较复杂,手动编写难度比较大,可通过官方提供的在线编辑来实现。

与SpringBoot集成

pom依赖包

  <!--引入swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

编写配置文件SwaggerConfig

/**
 * 主要是添加注解@EnableSwagger2和定义Docket的bean类。
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //是否开启swagger,正式环境一般是需要关闭的,可根据Springboot的多环境配置进行设置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled).select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("com.techstar"))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成和使用示例")
                .description("7DGroup | zuozewei")
                // 作者信息
                .contact(new Contact("zuozewei", "https://blog.csdn.net/zuozewei", "zuozewei@hotmail.com"))
                .version("1.0.0")
                .build();
    }
}

添加文档内容(一般上是在Controller,请求参数上进行注解)
添加MyGetMethod类,这里演示两个Get请求

@RestController
@RequestMapping("/")
@Api(tags = "API文档",value = "/",description = "这是我全部的Get方法")
public class MyGetMethod {

    @GetMapping(value = "/getCookies")
    @ApiOperation(value = "通过这个方法可以获取到Cookies",httpMethod = "GET")
    public String getCookies(HttpServletResponse response){
        //HttpServerletRequest 装请求信息的类
        //HttpServerletResponse  装响应信息的类
        Cookie cookie = new Cookie("login","true");
        response.addCookie(cookie);
        return "恭喜zuozewei获得cookies信息成功";
    }

    /**
     * 要求客户端携带cookies访问
     * 这是一个需要携带cookies信息才能访问的get请求
     */
    @GetMapping(value = "/get/with/cookies")
    @ApiOperation(value = "通过这个方法可以获取到Cookies",httpMethod = "GET")
    public String getWithCookies(HttpServletRequest request){
        Cookie[] cookies = request.getCookies();
        if (Objects.isNull(cookies)){
            return "必须携带cookies信息来";
        }
        for (Cookie cookie:cookies){
            if (cookie.getName().equals("login") && cookie.getValue().equals("true")){
                return "这是一个需要带着cookies信息才能访问的get请求";
            }
        }

        return "必须携带cookies信息来";
    }
}

配置全局配置文件application.properties

# 默认的端口号
server.port=8888

# 开启swagger
swagger.enabled=true

启动项目

在这里插入图片描述

Swagger-UI 访问与使用

API首页路径:http://127.0.0.1:8888/swagger-ui.html
在这里插入图片描述
点击需要访问的API列表,查看接口详情,点击try it out按钮测试在这里插入图片描述
执行测试

在这里插入图片描述

服务端返回结果
在这里插入图片描述

Swagger使用的注解及其说明:
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

  • l code:数字,例如400
  • l message:信息,例如"请求参数没填好"
  • l response:抛出异常的类

@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性

对于其他注解,大家可自动谷歌,毕竟常用的就这几个了。有了swagger之后,原本一些接口请求需要Postman这样的调试工具来进行发起,而现在直接在页面上就可以进行调试了,是不是很爽?
对于测试人员,有了这份API文档也是一目了然,不需要和后端多少沟通成本,按着API说明进行接口测试脚本开发即可。

小结

本文主要是对Swagger的简单使用和Springboot集成进行了说明,详细的用法,可自行搜索相关资料下,这里就不阐述了。因为对于百分之八十之上的文档要求基本能满足了。最后,一定要在生产环境关闭Swagger,基于安全因素。

项目源码地址:

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。