前言

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

概述

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

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

• Swagger

  *Swagger是一种和语言无关的规范和框架，用于定义服务接口，主要用于描述RESTful的API。它专注于为API创建优秀的文档和客户端库。支持Swagger的API可以为API方法生成交互式的文档，让用户可以通过以可视化的方式试验，查看请求和响应、头文件和返回代码，从而发现API的功能。它本身就非常强大，但是Swagger框架还支持为多种流行的语言——包括JavaScript、Python、Ruby、Java、Scala等等——生成客户端代码。*
  *网址： https://helloreverb.com/developers/swagger*
  

• Swagger-UI

  *为基于Swagger规范的API生成基于基于纯粹HTML,javascript,css的在线可视化文档，同时也能成为API的在线测试工具。*
  *网址： https://github.com/wordnik/swagger-ui*

• JSON Schema

  *类似于XSD对比与XML的关系，JSON schema是用来描述JSON数据类型的schema。*
  *网址：http://json-schema.org/*

• DOCSON

  *一个json数据的文档化工具，通过json schema生成对应的在线JSON可视化文档。*
  *网址：https://github.com/lbovet/docson*

• TypeScript

  *TypeScript是一种由微软开发的自由和开源的编程语言。它是JavaScript的一个超集，而且本质上向这个语言添加了可选的静态类型和基于类的面向对象编程。*
  *网址：http://www.typescriptlang.org/*

• Typeson

  *利用typescript这种面向对象的javascipt超集，生成json schema。*
  *网址：https://github.com/lbovet/typson*
  

在这个API的开发实践中，我们会贯彻两个理念：

1. Design-First 设计先行
2. TDD 测试驱动

从一个基本应用开始

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

数据模型设计

• 第一步，安装docson，从网址https://github.com/lbovet/docson，按照介绍，下载docson并且在web服务器里启动。可以用node.js或者部署到tomcat上。
  假设在tomcat上部署启动后，访问：http://localhost:8080/docson/index.html

可以看到如下页面：

说明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：

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

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

1. 除了手写外，我们也可以利用Typescript/typeson来辅助我们生成json schema
   具体可以参考网站和demo：http://lbovet.github.io/typson-demo/ 需要稍微熟悉下typescript

API接口的设计

在数据模型定义好后，我们接着可以定义具体需要的API列表和每个API的接口形式，请求方法，输入输出参数等具体信息。在此我们利用前面设计好的json schema，结合swagger-ui工具，就可以定义设计API列表。

• 第一步 准备好swagger-ui，部署并启动。参考网址： https://github.com/wordnik/swagger-ui
  这里我们将用swagger-ui的离线版本，先行设计API。
• 第二步 设计每个API，按功能组织分类, 将设计好的json schema引入，同时设计如下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在线文档：

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

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

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

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服务给第三方的平台开发者具有较大的价值。关于更多相关规范和工具的使用，希望大家参考对应网站提供的文档，深入掌握，也何以和作者交流