thinkjs+swagger Editor

        一直很好奇专门写接口同事的工做，因而趁着手边工做中的闲暇时间，特意看看神奇的接口文档怎么摆弄。

总览：

        这是基于thinkjs(3.0)，使用swagger editor编写，实现功能性测试的接口文档。

先了解一些必要的知识吧：

        1.）什么是Swagger？

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件；是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。整体目标是使客户端和文件系统做为服务器以一样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，容许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。（https://swagger.io/）

Swagger的目标是为REST APIs 定义一个标准的，与语言无关的接口，令人和计算机在看不到源码或者看不到文档或者不能经过网络流量检测的状况下能发现和理解各类服务的功能。当服务经过Swagger定义，消费者就能与远程的服务互动经过少许的实现逻辑。相似于低级编程接口，Swagger去掉了调用服务时的不少猜想。

        2.）Swagger Editor

能够直接使用在线编辑器https://editor.swagger.io/（左边编辑，右边实时效果），方便咱们直接写文档，并将其转成所需的json或者yaml格式。

        3.）为何使用？

①支持API自动生成同步的在线文档；②这些文档可用于项目内部API审核 ；③方便测试人员了解API。

开始吧：

        1.）建thinkjs项目：

特别说明：自从thinkjs升级到3.0后，本身就没有好好看看其中有什么变化，直至如今从新看的时候才发现3.0较2.0变化还挺大的，不只是文件目录变化，框架底层也发生了变化，关于这些仍是以为看官网会更清晰些：https://thinkjs.org/

        2.）关于swagger的一些配置

①https://github.com/swagger-api/swagger-ui中将dist文件夹copy出来，在新建项目中根目录下新建一个static文件夹，并将dist文件夹放进去

        注意：其中test.yaml文件是我在swagger editor中写好的接口文档转成的yaml格式的文件，而后放在dist目录下的；所以后来的大家也要进行相似的操做，在swagger editor中写好文档，转成所须要的格式再放进dist中，而后将dist/index.html中的url改为你等文件中test.yaml文件所在路径，即

        而后浏览器访问：（http://ip:8360/dist/test.yaml）即可以看见你的接口文档；（http://127.0.0.1:8360/dist/index.html）就能够看见带有swagger ui 的效果啦：

疑难杂症：

        其实回头想一想，作出这样的效果并不算难，但就是由于本身了解的太少。而在进行跨域访问的时候，还须要安装另一个组件：https://github.com/koajs/cors，在src/config/middleware.js中：

const cors = require('@koa/cors'); ... { handle: cors, options: {} }, ...

        But：有个问题：把thinkjs项目用vscode打开后，编译就出错，可是不影响运行（本身有点强迫症，每次看见这样就很想解决掉，无奈又没找出问题，也许恰巧你能解决，3ky~）

结尾：

        兴趣是最好的老师。由于喜欢，因此写起来也是满满的喜悦。最后感谢一直不吝赐教的晁州大神（http://www.cnblogs.com/vipzhou/）——昔日好同事，今日好朋友。

      2018，新一年的开始——叶叶Yeah开启疯狂奔跑模式吧！