Swagger介紹
在Web開發中，后端開發者在完成接口開發后，需要給前端相應的接口使用說明，所以一般會寫一份API文檔。一般來說，有兩種方式提供API接口文檔，一種是利用插件在代碼中自動生成，另一種是手工編寫API文檔。
Swagger就是為API文檔設計而生的，其中包含一整套相關工具，既支持利用插件在代碼中進行注解從而自動生成文檔，也支持手工編寫文檔。兩種方式各有優缺點：
- 自動生成：省時，方便。只需在編寫代碼的時候添加一點注解就可以幫你自動完成文檔的生成和部署。但是缺點也很明顯，對於比較復雜的接口，或者在參數中使用自定義參數解析器的接口，它的支持就不太完美，換句話說，生成的文檔很“死板”，里面可能有很多與預期不太符合的東西。（期待相關插件功能越來越完善，我相信有一天會完全取代手工編寫的方式）。
- 手工編寫：靈活性高，能夠完美的表達自己的想法。缺點就是需要額外的編寫，維護和管理。
接下來我對兩種方式分別做一下介紹。
自動生成
自動生成的方式還是比較容易的，對於不同的語言，有不同的插件以供使用。
- 如果你的后台用node編寫，可以使用koa-swagger-decorator來生成API文檔。
- 如果你的后台采用spring-boot方案，可以用springfox開發的一套插件來生成Swagger文檔。具體可以參考這個教程。
- 對於其他技術路線，讀者可以自行Google搜索是否有相關插件以供使用。
接下來我主要講解一下手工編寫的方式。
手工編寫
后台開發者在完成接口開發后，需要進行如下流程：
- 在Swagger Editor中編寫swagger.yaml文件（具體語法見官方教程，比較簡單）.
- 在Swagger Editor中將yaml文件導出為json文件。
- 利用Swagger UI渲染json文件，並且部署在服務器上。
其中前兩點比較容易，有比較好的參考教程，一步步走下來就行。而利用Swagger UI渲染並部署，稍微麻煩一些，下面我將自己的做法給大家分享一下。
首先，在開始之前，可以看看我們項目組的一個示例。這個 Swagger 是我部署上去的，可以比較方便的查看，並且利用Try it out功能可以進行實時的測試，這也是利用Swagger編寫API文檔很大的一個好處。
接下來正式講解如何使用Swagger UI渲染json文件，並且部署在服務器上。
Swagger-UI的官方倉庫里明確說明了：他們在npm倉庫里上傳了兩個npm模塊，分別是swagger-ui 和 swagger-ui-dist. 這兩種方式都需要npm的支持，也就是說我們需要在服務器上運行一個node程序來專門為swagger服務，特別是當我們的服務器端不是用node.js寫的時候，需要額外花費較大的精力和時間。那么我們有沒有辦法 不使用任何node.js庫，直接將Swagger UI部署在雲端呢？ 答案當然是有的，我們只需要充分利用官方倉庫中的/dist文件夾即可。具體步驟如下：
- 首先我們進入Swagger-UI的官方倉庫，將其克隆至本地.
- 進入倉庫中的
/dist文件夾，用瀏覽器打開index.html文件，這個時候，應該可以看到官方的Swagger PetStoreAPI實例文件已經打開並且成功渲染。 - 將我們撰寫的json文件上傳到雲端服務器上。確保能夠遠程訪問。(例如您可以嘗試我上傳的http://121.42.175.137/swagger.json, 能夠到達這個效果就算成功）
- 用編輯器打開2中的
index.html文件，將onload function中的url:"https://petstore.swagger.io/v2/swagger.json"改為自己服務器上json文件的URL。 - 再次用瀏覽器打開
index.html，成功訪問到我們自己的API文檔。 - 將
dist文件夾整個上傳到雲端服務器，即全部完成。
這個方法是我自己摸索出來的，主要是利用了dist文件夾已經擁有渲染json文件的全部能力，這里包含了所有的html, css, js，於是我們可以直接拿來用了～當然這樣也有一點缺陷，就是更新會不及時。官網上偶爾會更新dist文件夾，而我們的dist文件夾是不會自己更新的，但是也沒有太大關系。
本機渲染
以上方法基於擁有遠程服務器的前提。如果您想用此方法在本機上渲染json，同樣也是有方法的，只需要利用http-server或其他的本地服務器程序，將json文件掛到本機某一端口（例如8080），然后將index.html中的url改為localhost:8080/xxx.json即可。