最近一直在整理公司前輩寫的php后臺api模塊。發現api整理起來還是很麻煩的，而且很不直觀，為此跟app端的開發人員也有不少誤會。在網上找到了swagger，不得不說，swagger-ui的構建效果非常驚艷。
我在開發中使用的是swagger-api/swagger-ui以及zircote/swagger-php
在github上把這兩個拉取下來以后，首先可以通過拷備/swagger-php/Examples/petstore.swagger.io來生成自己的api文件夾，
這里面有4個文件需要根據自己的項目修改，具體如下。
-ApiResponse.php（api文檔基礎返回參數，默認返回code, msg字段）
-swagger-v2.php（swagger全局配置文件，如api使用協議http?https，主機等）
-tags.php(api分類標簽配置文件，如上面我就配置了一個new用于新聞接口)
修改好上面的的內容以后，就可以在controller文件夾下建立自己的api控制器了。swagger-php會自己讀取文件中的swagger注釋，并以些為基礎來生成json文檔。
<?php
namespace pet2storeIO;
final class NewController
{
/**
* @SWG\Post(
* path="/guestbook/appmsg",
* summary="訪客留言",
* tags={"new", "guest"},
* description="訪客留言",
* operationId="appmsg",
* @SWG\Parameter(
* description="msg",
* format="string",
* in="formData",
* name="msg",
* required=true,
* type="string",
* ),
* @SWG\Parameter(
* description="email",
* format="string",
* in="formData",
* name="email",
* required=true,
* type="string",
*
* ),
* consumes={"multipart/form-data", "application/x-www-form-urlencoded"},
* produces={"application/json"},
* @SWG\Response(
* response="200",
* description="返回成功",
* ),
* )
*/
public function appmsg()
{
}
}
修改完成以后，可能通過swagger-php/bin下的應用直接生成swagger.json以供swagger-ui來讀取使用。
如果要發布，只需要將swagger-ui中的dist文件夾上傳到服務器，同時修改dist中的index.html，里面一行，將其地址改在swagger.json上傳的地址即可。
后記
在基本完成自己的api文檔之后，我發現swagger-php的生成工具有點過于重復勞動而且比較繁瑣，其主要的工作也就是生成swagger.json，而如果api不需要寫得很復雜的話，swagger本身提供了一個很好用的在線工作。swagger-editor(http://editor.swagger.io/)
通過他就可以很快的編輯了。(!T_T!)
當然啦，這只是我個人的評判感受，這兩種工具大家也可以都用一下，比較下個中優劣。
