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