swagger:php后台api文档生成初试

最近一直在整理公司前辈写的php后台api模块。发现api整理起来还是很麻烦的，而且很不直观，为此跟app端的开发人员也有不少误会。在网上找到了swagger，不得不说，swagger-ui的构建效果非常惊艳。

Paste_Image.png

我在开发中使用的是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来读取使用。

Paste_Image.png

如果要发布，只需要将swagger-ui中的dist文件夹上传到服务器，同时修改dist中的index.html，里面一行，将其地址改在swagger.json上传的地址即可。

Paste_Image.png

后记

在基本完成自己的api文档之后，我发现swagger-php的生成工具有点过于重复劳动而且比较繁琐，其主要的工作也就是生成swagger.json，而如果api不需要写得很复杂的话，swagger本身提供了一个很好用的在线工作。swagger-editor(http://editor.swagger.io/)

Paste_Image.png

通过他就可以很快的编辑了。(!T_T!)
当然啦，这只是我个人的评判感受，这两种工具大家也可以都用一下，比较下个中优劣。