基于Swagger的RESTful API开发之工具篇

基于Swagger的RESTful API开发之工具篇

一、数据模型设计(docson)

数据模型设计采用docson + Typson + TpyeScript.
其中，TpyeScript是一个javascript超集。
Typson是利用TpyeScript语言编程代码生成JSON Schema的工具。
docson是通过json schema生成对应的在线JSON可视化文档的工具。

typson-demo是一个整合好在线编辑工具。可以通过http://hi104.github.io/types cript-playground-on-ace/ 在线体验。

使用方法

1. 安装typson-demo，实际上这只是一个web项目，将它放在任何一个web服务器容器中中启动服务器，在浏览器中访问即可，例如我使用的是tomacat服务器，将typson-demo项目下载下来被解压后（文件夹名称是typson-demo-gh-pages）放在tomcat的webapps目录中，启动服务器访问http://localhost:8081/typson-demo-gh-pages/index.html 即可。这一步在注意typson-demo项目文件夹里没有放docson 和 Typson 相关的js，因此需要自己下载docson + Typson放入文件夹中。

2. 在typson-demo可视化的完成数据模型设计

3. 将完成的TpyeScript保存到一个ts文件中，使用typson对ts文件进行转换，生成JSON schema文件

二、API接口设计

分两步完成API接口设计

使用SWAGGER EDITOR工具在线可视化编辑API

这个工具有在线版的：http://editor.swagger.io/#/
也可以下载使用离线版本。具体可以参考 http://swagger.io/swagger-editor/ 中的介绍
在安装的时候发现github上没有dist文件，需要自己从http://editor.swagger.io/#/ 上面去扒下来。

使用的是yml文件语法。

使用swagger-ui生成API文档

这里使用 SWAGGER UI 进行文档生成。工具地址是 http://swagger.io/swagger-ui/。
这个工具也有在线版和离线版本，由于要访问上个步骤生成的JSON文件，建议下载离线版本在本地部署使用。
这里提醒一下，swagger-ui下载下来的zip包中dist目录才是项目可以运行的目录。

1. 在上一步完成接口设计后，使用File -> JSON生成JSON文件。
2. 将json文件放置在SWAGGER UI可以访问到的地址，在http://localhost:8081/swagger-ui/dist/ 页投输入资源的URL地址，回车或点击Explore即可看到API文档，并且可以在上面做测试。

三、工程测试

使用swagger-codegen可以根据接口生成测试时使用的客户端或服务端的测试代码，方便前后端分离进行开发。

这一块还要具体使用下再说明，下次再补充。