從此接口文檔成為一笑而過，從此服務端不再被客戶端追債似得要接口文檔
主要內容：
1、項目背景
2、Swagger應用
3、總結
項目背景
作為一個服務端開發人員，我相信大多數的同學都會和客戶端開發同學溝通接口問題。
但是啊，但是，每當我們高高興興的開發完成，告訴客戶端和前端同學可以調試的時候，通常大家會問一句“文檔呢？”。於是，服務端像是被追債似的加緊時間寫文檔，寫的慢了還要承擔耽誤開發的責任~寫文檔很枯燥有木有，寫文檔很無聊有木有，我們是開發，不是文員啊，大把時間不用來coding，用來寫文檔，各種表格排版，很頭疼啊頭疼啊頭疼啊（重要的事情說三遍）~ 總之，不管別人喜不喜歡寫文檔，我是不喜歡寫的，而且寫了還要改來改去的╮(╯▽╰)╭。
終於在陽光明媚的一天，我找到了一個自動生成文檔框架swagger！！！！暗淡的日子終於迎來了曙光。
PS：抱怨吐槽結束，客戶端勿怪，客戶端的同學都是很可愛噠。
Swagger應用
這章內容說正經的——如何搭建框架。
此框架目前應用項目——英語口語精華，本項目為php開發，進行swagger、php整合，但是swagger對於java的支持更為優秀，有興趣的同學可以自行百度（當然google更洋氣）。
swagger簡介
Swagger的使用目的是方便優美的呈現出接口API的各種定義, 生成API文檔, 包括參數, 路徑之類. 有時后端改了API的參數或者其他設置，同時對於restful風格接口有更加優雅的展示, 前端直接看這個Swagger UI就可以, 方便項目管理和團隊協作.。
這東西咋用呢? 說白了就是安裝Swagger套件, 然后API代碼里寫注釋, 用Swagger后端程序跑API來提取注釋, 生成一個json文件, 再通關Swagger前端來美化,整理JSON數據.
多說顯得嘮叨，上效果圖
swagger搭建過程
swagger主要分為兩個部分，swagger-ui和swagger-php，ui用於展示，后者用於生成相關api。
首先，在自己項目的合理位置上下載前端ui和生成的php。放在項目里面是為了保證訪問地址和咱們接口地址都在一起，不會是訪問時產生跨域問題。
swagger-ui：https://github.com/swagger-api/swagger-ui.git
swagger-php：https://github.com/zircote/swagger-php.git
第一步：ui搭建
在ui里面有個dist文件夾，修改文件夾里面index.html文件，將url里的位置寫成自己的項目地址
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://XXXX/doc/swagger.json";
}
hljs.configure({
highlightSizeThreshold: 5000
});
到此位置我們的ui已經配置完了。
第二步：生成環境搭建
下載swagger-php后，進入此文件夾，使用composer下載swagger-php下載swagger-php所需要的依賴，使用命令行，輸入（前提是安裝了composer）：
composer update
這樣后台就算完成了搭建，我們的swagger-php多了vender文件夾
第二步：代碼注解
在我們的controller的文件中編寫注解，舉個栗子
/**
- @SWG\Get(
- path="/pets",
- description="Returns all pets from the system that the user has access to",
- operationId="findPets",
- produces=
Unknown macro: {"application/json", "application/xml", "text/xml", "text/html"},
- @SWG\Parameter(
- name="tags",
- in="query",
- description="tags to filter by",
- required=false,
- type="array",
- @SWG\Items(type="string"),
- collectionFormat="csv"
- ),
- @SWG\Parameter(
- name="limit",
- in="query",
- description="maximum number of results to return",
- required=false,
- type="integer",
- format="int32"
- ),
- @SWG\Response(
- response=200,
- description="pet response",
- @SWG\Schema(
- type="array",
- @SWG\Items(ref="#/definitions/pet")
- ),
- ),
- @SWG\Response(
- response="default",
- description="unexpected error",
- @SWG\Schema(
- ref="#/definitions/errorModel"
- )
- )
- )
*/
還有其他的一些寫法，swagger-php/Example里都有可以照着抄就行。
第三步：文檔生成
第三步也是最重要的一步，生成相關api，生成方式十分簡單，只需要在命令行里執行命令
php swagge-php/bin/swagger 接口文件夾 -o 生成的目的文件夾
目的文件夾建議寫在項目文件夾下，也是為了避免跨域問題。
第四步：部署
最后只剩下把自己的api進行部署了，我們的項目是與nginx進行結合，所以需要簡單配置一下，替換自己的路徑就可以了
location ~ ^/doc/
location ~ ^/dist/
至此，一切大功告成~\(≧▽≦)/~，終於可以逃離寫文檔的噩夢了
總結：
說一下使用的好處吧。
第一，當然是不用寫文檔了；
第二，測試同學可以通過接口文檔進行接口測試。