Open ghost opened 7 years ago
author：Spring email：389055604@qq.com
之前参与一个项目的开发，该项目分Web网页端、wpf桌面程序端和app，还有一个后台服务server，并提供一个后台管理系统和一个类似在线商城的系统。各端需要数据同步，并传递统一格式的json数据。而我主要负责app和网页端开发。
后台开发写好了基本接口，并提供了一个简单的API说明的Word，然后我们各端就先后开始启动了。而我在开始做app的时候，桌面程序端已经具备较完善的功能了。然后api和数据格式也根据桌面程序端进行了一些相应的修改，也新增了一些接口，可以说我开始做app的时候是不用担心数据服务的问题。 但是我想得太美好了。首先，原来的api文档已经完全不能用了，因为在桌面程序开发和后台开发一路吵过来之后，api已经变得面目全非，但是没有最新的api文档，纳尼？
好吧，我和后台进行沟通：QQ消息，截图，查看后台代码（汗...），终于跑通了几个接口，起码能请求到正确的数据了。可是，我完全不能忍，没有API文档实在是太费劲了，动不动就跑去后台叫打个断点，估计后台那哥们也被我弄烦了，然后补上了接口注释，然后生成了一个帮助文档，总算是轻松了一点。
但是事情还没完，当我要请求一个api的时候，往往会返回一个错误，但是我并不能很直观的确定是什么引起的错误，还是要频繁的找后台调试。而且要测试一个api，需要在代码中写很多测试代码，或者硬编码一长串数据，这时候要是有一个能直观的测试api的工具该多好。swagger UI正好可以帮助我们完成这些事情。
Swagger UI是一个API在线生成和测试的工具。swagger UI是swagger项目的一部分，主要用于RestFul风格接口文档的在线生成和测试。swagger UI是一个无其他依赖的HTML、JS和CSS的集合，因此它能方便的集成到各种web服务中。
swagger UI通过加载描述有rest接口的json或者yaml文件，并以网页的形式展现出来，让我们可以直观的查询接口定义和数据结构描述，并且能在线直接测试接口的可用性和正确性。 在网页中看API文档就长这样。 其中某一个API长这样。 填好参数后还能直接进行测试，就像这样。在这里可以直接查看api返回的数据，再也不用编程写一堆代码去测试api了。
swagger UI下载地址，可以直接下载zip包： https://github.com/swagger-api/swagger-ui swagger UI可以部署到服务器中，在这里我部署到本地node服务中。
创建一个空文件夹
mkdir swagger_ui_demo && cd swagger_ui_demo
初始化node，创建package.json文件
npm init
安装express
npm install express --save
新建一个index.js文件，编写服务端代码
var express = require('express'); var app = express(); //托管public下静态文件 app.use('/static',express.static('public')); //允许跨域 app.all('*', function(req, res, next) { res.header("Access-Control-Allow-Origin", "*"); res.header("Access-Control-Allow-Headers", "X-Requested-With"); res.header("Access-Control-Allow-Methods","PUT,POST,GET,DELETE,OPTIONS"); res.header("X-Powered-By",' 3.2.1') res.header("Content-Type", "application/json;charset=utf-8"); next(); }); app.get('/',function (req,res) { res.send('hello world!'); }); app.listen(3000);
运行index.js文件
node index
浏览器中打开http://localhost:3000/static/index.html,可以看到swagger ui的demo首页。
现在还只是swagger UI的demo页面，实际中我们应该看到的是我们自己的api文档。
之前说过SU（swagger UI）是通过一个JSON文件来进行描述的，所以我们应该有自己的json描述文件。我们先来看看这个JSON文件长什么样，复制SU Demo页输入框中的链接，在浏览器中打开，可以直接保存到本地用编辑器打开，然后我们就看到了这个json文件的样子。也可以通过这个链接打开swagger editor，然后下载他的示例json文件。（稍后介绍swagger editor，它就是一个SU json文件编辑工具，并且可以实时的预览生成的页面）
将json文件保存到public目录下，修改public目录下的index.html 文件，让其加载我们本地的json描述文件。
url = "/static/swagger.json";
然后刷新网页，这就可以看到我们本地的api文档了。可以试着修改里面的内容然后在网页中查看。 SU描述文档可以是JSON格式，也可以是yaml格式，SU官方使用的yaml格式，并且有专门的编辑器。json格式数据和yaml格式数据是一一对应的，只是编写的方式不一样，两种文档的语法都不难，基本看个几分钟，然后边修改边查看就会了。这里我们以官方yaml语法来进行学习。
打开swagger editor，可以看到如下界面。
这里有一些swagger官方的yaml格式的描述文档。 左边为yaml文档，右边显示生成的网页，左边编辑右边可以实时显示结果，可以方便的编写API文档，网页样式不一样可能是因为swagger UI版本不一样。我们可以在这里新建自己的api说明文档，也可以导入其他已存在的文档，还可以把swagger editor集成到本地，在本地编辑和生成api文档。后面再介绍怎么制作自己的api说明文档。
首先看示例文档的一级属性，大概是这样。
swagger指定使用的swagger版本，这个属性必不可少，不然会报错。
swagger
info为文档添加描述信息，包括标题，简介，版本等子属性。
info
host指定api的请求地址。实际应用中应该为我们的服务器。
host
schemes指定api请求时使用的协议方式的数组，如http、https
schemes
basePath为请求api时基本路径。api的最终路径为host + basepath + path。这个可以得到验证，在我们刚才本地建立的SU服务中，我们随便选择一个进行api测试。可以看到我们请求的路径包含了host和basepath，还有api自己的路径。这里报错是因为我没改host地址。
basePath
produces说明我们请求api时发送与返回的数据格式。
produces
paths这里就是指定我们api的地方了，包含api的路径，不同rest请求时的参数值、返回值等。
paths
definitions定义我们的数据model。paths中可以引用这些model，来表示请求参数或者返回值具有的数据格式。主要是定义一个通用的数据结构。
definitions
下面来看一下一个api接口是如何定义的。
一个api应该包含一个路径，如这里的/products，关于它的描述定义应该作为它的属性。需要说明的是api说明文档默认都是key-value形式的，一个属性对应一个值。
/products
该路径下可以定义不同rest风格的请求，如这里的get，然后则是该请求下的具体定义。
get
上面的返回值中使用了一个引用类型：
$ref: '#definitions/Product'
该类型的定义在definitions中
这个结构的定义很简单，就是一个json数据格式，所以不再单独介绍。这里定义的值类型，可以被其他api接口所引用，只要它的值具有这个结构就可以直接引用它。
好了，现在就定义好了一个get方式的products的接口。我们可以在网页进行查看和测试了。
json方式文档与yaml文档类似，属性名都是一样的，而且是一一对应，所以这里不赘述json文档的语法格式。
swagger editor是官方提供的在线编辑说明文档的工具，前面已经见过了，但是需要我们连接网络。在这里我们可以将其集成到我们本地。
将下载的文件解压。该项目是一个nodejs项目，安装node依赖。（需要安装git）
npm install
运行服务，然后程序会打开一个网页，然后就看到我们本地的editor了。
npm start
我们还可以下载一个纯净的HTML、JS、css的swagger editor源码，然后部署到我们的服务器中。
现在则可以在本地进行编辑了。不太方便的是该编辑器只能进行yaml文档的编辑。
sosoapi的口号是专注于API接口文档管理和线上线下测试的服务平台。其使用是免费的。
sosoapi通过表单形式来创建接口描述，让我们更加专注于写接口内容，免去了写json文档时的排版、重复的敲属性名等工作。同时接口的编写和管理变得清晰明了，不再是一堆的json数据。
sosoapi生成的是基于swagger UI文档格式的json，即可在线进行测试，也可以下载下来部署到自己的服务器上。
sosoapi提供了另外一个项目成员管理功能。我们可以通过邮件邀请其他成员进入项目组，还可以给成员分配角色，并且在接口变化时通过邮件通知各类成员。
比较遗憾的是sosoapi没有提供在线预览功能，目前也没提供在线测试接口功能。
接口文档是可以自动生成，但是需要后台在接口定义时引入swagger，并且在接口定义时书写符合规范的文档注释。
此方法需要后台必须为每个接口书写文档注释。然后swagger会读取这些注释自动生成一个json文件。如果我们再把swagger UI集成进来，那么便能在服务运行时直接访问api文档了。
具体实现方式这里不做介绍。
swagger-UI入门
学习前思考
之前参与一个项目的开发，该项目分Web网页端、wpf桌面程序端和app，还有一个后台服务server，并提供一个后台管理系统和一个类似在线商城的系统。各端需要数据同步，并传递统一格式的json数据。而我主要负责app和网页端开发。
后台开发写好了基本接口，并提供了一个简单的API说明的Word，然后我们各端就先后开始启动了。而我在开始做app的时候，桌面程序端已经具备较完善的功能了。然后api和数据格式也根据桌面程序端进行了一些相应的修改，也新增了一些接口，可以说我开始做app的时候是不用担心数据服务的问题。
但是我想得太美好了。首先，原来的api文档已经完全不能用了，因为在桌面程序开发和后台开发一路吵过来之后，api已经变得面目全非，但是没有最新的api文档，纳尼？
好吧，我和后台进行沟通：QQ消息，截图，查看后台代码（汗...），终于跑通了几个接口，起码能请求到正确的数据了。可是，我完全不能忍，没有API文档实在是太费劲了，动不动就跑去后台叫打个断点，估计后台那哥们也被我弄烦了，然后补上了接口注释，然后生成了一个帮助文档，总算是轻松了一点。
但是事情还没完，当我要请求一个api的时候，往往会返回一个错误，但是我并不能很直观的确定是什么引起的错误，还是要频繁的找后台调试。而且要测试一个api，需要在代码中写很多测试代码，或者硬编码一长串数据，这时候要是有一个能直观的测试api的工具该多好。swagger UI正好可以帮助我们完成这些事情。
swagger UI简介
Swagger UI是一个API在线生成和测试的工具。swagger UI是swagger项目的一部分，主要用于RestFul风格接口文档的在线生成和测试。swagger UI是一个无其他依赖的HTML、JS和CSS的集合，因此它能方便的集成到各种web服务中。
swagger UI通过加载描述有rest接口的json或者yaml文件，并以网页的形式展现出来，让我们可以直观的查询接口定义和数据结构描述，并且能在线直接测试接口的可用性和正确性。
其中某一个API长这样。
填好参数后还能直接进行测试，就像这样。
在这里可以直接查看api返回的数据，再也不用编程写一堆代码去测试api了。
在网页中看API文档就长这样。
使用swagger UI
swagger UI下载地址，可以直接下载zip包： https://github.com/swagger-api/swagger-ui
swagger UI可以部署到服务器中，在这里我部署到本地node服务中。
本地环境搭建
创建一个空文件夹
初始化node，创建package.json文件
安装express
新建一个index.js文件，编写服务端代码
运行index.js文件
浏览器中打开http://localhost:3000/static/index.html,可以看到swagger ui的demo首页。
现在还只是swagger UI的demo页面，实际中我们应该看到的是我们自己的api文档。
之前说过SU（swagger UI）是通过一个JSON文件来进行描述的，所以我们应该有自己的json描述文件。我们先来看看这个JSON文件长什么样，复制SU Demo页输入框中的链接，在浏览器中打开，可以直接保存到本地用编辑器打开，然后我们就看到了这个json文件的样子。也可以通过这个链接打开swagger editor，然后下载他的示例json文件。（稍后介绍swagger editor，它就是一个SU json文件编辑工具，并且可以实时的预览生成的页面）
将json文件保存到public目录下，修改public目录下的index.html 文件，让其加载我们本地的json描述文件。
然后刷新网页，这就可以看到我们本地的api文档了。可以试着修改里面的内容然后在网页中查看。 SU描述文档可以是JSON格式，也可以是yaml格式，SU官方使用的yaml格式，并且有专门的编辑器。json格式数据和yaml格式数据是一一对应的，只是编写的方式不一样，两种文档的语法都不难，基本看个几分钟，然后边修改边查看就会了。这里我们以官方yaml语法来进行学习。
yaml & json语法
打开swagger editor，可以看到如下界面。
这里有一些swagger官方的yaml格式的描述文档。 左边为yaml文档，右边显示生成的网页，左边编辑右边可以实时显示结果，可以方便的编写API文档，网页样式不一样可能是因为swagger UI版本不一样。我们可以在这里新建自己的api说明文档，也可以导入其他已存在的文档，还可以把swagger editor集成到本地，在本地编辑和生成api文档。后面再介绍怎么制作自己的api说明文档。
首先看示例文档的一级属性，大概是这样。
swagger指定使用的swagger版本，这个属性必不可少，不然会报错。info为文档添加描述信息，包括标题，简介，版本等子属性。host指定api的请求地址。实际应用中应该为我们的服务器。schemes指定api请求时使用的协议方式的数组，如http、httpsbasePath为请求api时基本路径。api的最终路径为host + basepath + path。这个可以得到验证，在我们刚才本地建立的SU服务中，我们随便选择一个进行api测试。produces说明我们请求api时发送与返回的数据格式。paths这里就是指定我们api的地方了，包含api的路径，不同rest请求时的参数值、返回值等。definitions定义我们的数据model。paths中可以引用这些model，来表示请求参数或者返回值具有的数据格式。主要是定义一个通用的数据结构。下面来看一下一个api接口是如何定义的。
一个api应该包含一个路径，如这里的
/products，关于它的描述定义应该作为它的属性。需要说明的是api说明文档默认都是key-value形式的，一个属性对应一个值。该路径下可以定义不同rest风格的请求，如这里的
get，然后则是该请求下的具体定义。上面的返回值中使用了一个引用类型：
该类型的定义在
definitions中这个结构的定义很简单，就是一个json数据格式，所以不再单独介绍。这里定义的值类型，可以被其他api接口所引用，只要它的值具有这个结构就可以直接引用它。
好了，现在就定义好了一个get方式的products的接口。我们可以在网页进行查看和测试了。
json方式文档与yaml文档类似，属性名都是一样的，而且是一一对应，所以这里不赘述json文档的语法格式。
使用什么工具编写json文档？
swagger editor
swagger editor是官方提供的在线编辑说明文档的工具，前面已经见过了，但是需要我们连接网络。在这里我们可以将其集成到我们本地。
将下载的文件解压。该项目是一个nodejs项目，安装node依赖。（需要安装git）
运行服务，然后程序会打开一个网页，然后就看到我们本地的editor了。
我们还可以下载一个纯净的HTML、JS、css的swagger editor源码，然后部署到我们的服务器中。
现在则可以在本地进行编辑了。不太方便的是该编辑器只能进行yaml文档的编辑。
sosoapi
sosoapi的口号是专注于API接口文档管理和线上线下测试的服务平台。其使用是免费的。
sosoapi生成的是基于swagger UI文档格式的json，即可在线进行测试，也可以下载下来部署到自己的服务器上。
sosoapi提供了另外一个项目成员管理功能。我们可以通过邮件邀请其他成员进入项目组，还可以给成员分配角色，并且在接口变化时通过邮件通知各类成员。
比较遗憾的是sosoapi没有提供在线预览功能，目前也没提供在线测试接口功能。
通过接口注释自动生成
接口文档是可以自动生成，但是需要后台在接口定义时引入swagger，并且在接口定义时书写符合规范的文档注释。
此方法需要后台必须为每个接口书写文档注释。然后swagger会读取这些注释自动生成一个json文件。如果我们再把swagger UI集成进来，那么便能在服务运行时直接访问api文档了。
具体实现方式这里不做介绍。