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開啓瘋狂奔跑模式吧！