最近一直在整理公司前辈写的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!)
当然啦，这只是我个人的评判感受，这两种工具大家也可以都用一下，比较下个中优劣。
