"Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment."
Swagger是一款基于OpenAPI規(guī)范的API開發(fā)工具框架，從設計、文檔、測試和部署支持整個API開發(fā)的生命周期。
其中Swagger Ui 能夠動態(tài)的生成漂亮的API文檔。
這里來講一下Swagger Ui的搭建與基本使用方法。
本地搭建
準備：
- Node 6.x
- NPM 3.x
以上。這是官網提供的參數，我本地使用的node是7.10.0。
下載：
- 訪問github下載整個包。
- 或使用git工具下載
git clone https://github.com/swagger-api/swagger-ui.git
dev環(huán)境
npm run dev
打開http://localhost:3200就可以看到頁面了。
生產環(huán)境
下載的包中的dist文件夾為swagger預生成的包，可以直接使用。
若是需要自定義開發(fā)，可以修改后使用npm run build進行再次編譯。
使用
如果只是上面的搭建的話，通常情況下不能完全滿足需求。比如：
- 雖然Swagger提供了配套的Editor編輯工具，我們仍然需要做點工作將兩者結合起來。
- 雖然Swagger Editor的語法簡單，但是對于初上手的開發(fā)者而言仍然有一定的上手成本，在團隊中推廣存在一定困難。
為此，我們需要做點別的工作。
搭建配套設施
（1）新建項目
新建一個express項目，接入Swagger UI.
yarn add express --dev
把上面的dist文件復制到項目文件下。
<pre>
-express
-index.js
-package.json
-src
-index.html
-swagger-ui.js
-... // 一整個復制過來
</pre>
然后開啟express服務就可以將swagger UI跑起來了。
（2）新建API文檔
在swagger Ui會分析Url中的參數來進行動態(tài)生成文檔，如：http://localhost:3200/?url=http://localhost:3200/static/eg.json那么變會根據eg.json來生成API文檔。
用express的static為項目中的json提供靜態(tài)地址。
<pre>
const app = express();
app.use('/static', express.static('./json'));
</pre>
然后新增路由，添加上傳接口。將用Swagger Editor生成的json上傳到服務器中。
（3）可視化圖形界面
上面第二條中，使用者仍然需要自己編寫yaml，然后上傳Json。使用體驗不佳。所以可以自己寫一個圖形界面的API文檔輸入界面，然后生成json。
