专栏首页7DGroup走进Java接口测试之接口管理工具Swagger2

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

前言

现在都奉行前后端分离开发和微服务大行其道,前后端技术在各自道路上越走越远。 前后端唯一联系变成了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.xml依赖包

<!--引入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列表,查看接口详情,点击 tryitout按钮测试

执行测试

服务端返回结果

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集成进行了说明,详细的用法,可自行搜索相关资料下,这里就不阐述了。对于百分之八十之上的API文档要求基本能满足了。最后,一定要在生产环境关闭Swagger,基于安全因素。

本文分享自微信公众号 - 7DGroup(Zee_7DGroup),作者:左泽位

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2018-12-06

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Visual Studio 中使用 SonarLint 分析 C# 代码

    现如今大家越来越认识到质量前移的重要性。如果一开始就写出优质的、经过测试的代码,那么后面的测试阶段将会减少很多不必要的时间。如果开发人员迫于业务压力,一味追求项...

    高楼Zee
  • 性能测试实战30讲」之问题问答整理三

    你能思考一下,为什么 258 响应时间不合理吗?像“业务模型用 28 原则”这些看似常识性的知识点,错在哪里呢?

    高楼Zee
  • 性能分析之OS资源饱和度

    在做性能分析的时候,我们不可避免地判断资源到底够不够用?哪里不够?为什么不够?证据是什么?

    高楼Zee
  • Swagger详细了解一下(长文谨慎阅读)

    Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specification(OpenAPI 规范,也简称 OAS)。 Swagger 可以...

    IT苦逼一枚
  • ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中:

    依乐祝
  • Swagger自动生成API文档

    最近安装并使用了一下Swagger-ui、Swagger-editor和Swagger-codegen,感觉还不错。

    javascript.shop
  • Spring Boot & MyBatis的种子项目

    一个基于Spring Boot & MyBatis的种子项目,用于快速构建中小型API、RESTful API项目~

    凯哥Java
  • 【你找茬儿,我发奖】腾讯云API文档“捉虫”活动

    登录腾讯云官网,进入API中心,选择感兴趣的产品,参照API文档指引进行实操测试。

    腾讯云文档
  • 精选前端面试题之HTML5/CSS3

    HTML是一种基本的WEB网页设计语言,XHTML是一个基于XML的置标语言 最主要的不同: XHTML 元素必须被正确地嵌套。 XHTML 元素必须被关...

    Javanx
  • 浅议 Promise/Futures 模型 [每日前端夜话(0x11)]

    随着 JavaScript 使用的不断增加,异步事件驱动的应用程序变得越来越流行。 但是,许多开发者经常面临的一个问题是:在异步环境中进行依赖于结果的操作。

    疯狂的技术宅

扫码关注云+社区

领取腾讯云代金券