基于 swagger 的 RESTful API 开发实践

阅读 2241
收藏 52
2016-06-27
原文链接:yq.aliyun.com

基于swagger的RESTful API开发实践

摘要: 前言 RESTful架构,是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。后端通过提供一套标准的RESTful API,让网站,移动端和第三方系统都可以基于API进行数据交互和对接,极大的提高系统的开发效率,也使得前后端分离架构成为可能。 ...

前言

RESTful架构,是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。后端通过提供一套标准的RESTful API,让网站,移动端和第三方系统都可以基于API进行数据交互和对接,极大的提高系统的开发效率,也使得前后端分离架构成为可能。
因此,不同的测试,开发团队(前端,移动端,第三方接入者等)都需要围绕API进行开发工作,API的规范和文档对于团队开发,测试变得越来越重要。除了一份标准的文档,我们还希望API能够在线测试使用,从而有更直观的API使用体验,降低API的学习成本。这些对于团队的开发协作都会事半功倍。 
本文将介绍一些API文档和开发测试方面的一些实践,使用typeson,docson,swagger-ui等开源工具,建立一个API的集设计,实现,测试,文档的一体化可视平台,让API的开发和使用更加高效。

概述

首先我们会通过一个简单系统的RESTful API的开发,介绍如果利用typeson,docson,swagger-ui等工具辅助API的设计和开发,掌握这些工具的使用,提高API的开发效率,质量。

在这个实例的开发中,会涉及到以下规范和工具:

在这个API的开发实践中,我们会贯彻两个理念:
1. Design-First 设计先行
2. TDD 测试驱动

从一个基本应用开始

 这部分我们假设开发团队接到一个新的开发需求,开发一个客户邮件营销系统,注册用户可以管理自己的客户,并通过邮件对客户进行营销活动。所有的后台功能通过RESTful API形式提供服务,网站开发,移动端开发,和后端同时进行开发。
首先团队之间需要沟通协调设计API接口设计,形成规范和文档。这就是我们常说的设计先行理念。

数据模型设计

说明docson已经准备好了

  • 第二步,根据业务需要设计json schema:
    1. 我们可以直接手写json schema,入将以下文件保存为/examples/user.json:
"$schema":"http://json-schema.org/draft-04/schema#",
    "title":"User",
    "description":"用户schema",
    "type":"object",
    "properties":{
        "id":{
            "description":"id",
            "type":"number"
        },
        "username":{
            "description":"用户名",
            "type":"string"
        },
        "password":{
            "description":"密码",
            "type":"string"
        },
        "fullname":{
            "description":"全名",
            "type":"string"
        },
        "telphone":{
            "description":"电话号码",
            "type":"string"
        },
        "email":{
            "description":"Email",
            "type":"string"
        },
        "company":{
            "description":"公司名",
            "$ref":"#/definitions/Company"
        },
        "customers":{
            "description":"客户",
            "type":"array",
            "items":{
                "$ref":"#/definitions/Customer"
            },
            "minItems":1,
            "uniqueItems":true
        },
        "mailTemplates":{
            "description":"模板",
            "type":"array",

将对应的地址http://localhost:8080/docson/examples/user.json 输入docson,回车后将看到图形化的schema:
A2

点击Customer等按钮可以查看对应的跟详细的数据类型信息:
A3

这样所有人员都可以直接查看数据模型的定义,协同设计。

API接口的设计

在数据模型定义好后,我们接着可以定义具体需要的API列表和每个API的接口形式,请求方法,输入输出参数等具体信息。在此我们利用前面设计好的json schema,结合swagger-ui工具,就可以定义设计API列表。
"apis":[
        {
            "path":"/accounts/",
            "operations":[
                {
                    "parameters":[
                        {
                            "name":"account",
                            "description":"Create a new account",
                            "required":true,
                            "dataType":"Account",
                            "paramType":"body"
                        }
                    ],
                    "responseMessages":[
                        {
                            "code":401,
                            "message":"Unauthorized"
                        },
                        {
                            "code":500,
                            "message":"Internal Application Error"
                        }
                    ],
                    "httpMethod":"POST",
                    "notes":null,
                    "responseClass":"Account",
                    "nickname":"createAccount",
                    "summary":"Create a new account",
                    "produces":[
                        "application/json"
                    ]
                }
            ]
        },

完成后,我们将可以得到如下的API在线文档:
A5

如某个具体AP,获取账户的具体信息
A6

如果API已经准备好,或者后端提供了一个mock实现,那么直接点击“try it out”,就可以直接调用该API,输入测试数据,测试返回数据和错误信息。

同时根据数据模型的json schema,swagger-ui 会自动生成对应json数据的form表单,无论结构多复杂,这极大方便API使用者对API的上手和测试。
A7

API的开发测试

到目前阶段,我们可以看到,及时API完全没有编码实现,我们也有一个很清晰的API文档和测试环境。各个开发测试团队可以在这个在线文档和测试平台上,协同各自开发测试。比如:
  • API开发团队根据这个文档,开发实现具体的API功能
  • 前端团队或者移动端,根据这个API文档,分别独自开发各自功能,mock API的实现。
  • 测试团队可以直接根据这个API的测试平台,利用selenium工具录制测试脚本和准备测试数据,在开发团队实现前就可以把测试准备好,用测试驱动开发

API使用阶段

 在API开发测试完成后,需要提供API给外部系统使用,我们可以直接把这个swagger-ui建立的在线文档和测试平台提供给开发使用者,作为标准的文档和测试工具。这样也不需要格外写一份静态的接口文档给用户,我们提供的是一份标准的live文档和测试工具,可以极大的方便使用着了解API,减低使用者的学习成本。

总结

本文只是简单的介绍了RESTful API开发中利用一些工具进行辅助开发,希望docson,typeson,swagger-ui 等纯粹的基于html,javascript的前端工具能够方便大家的API开发,建立一个API的在线文档和测试中心。这对于需要提供API服务给第三方的平台开发者具有较大的价值。关于更多相关规范和工具的使用,希望大家参考对应网站提供的文档,深入掌握,也何以和作者交流

扫我,和云栖在线交流

【云栖快讯】云栖直播频道上线,来这里一起围观阿里技术专家分享!  详情请点击
评论