需求: 为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用自动化文档工具前手写文档的血泪史. 我的故事却又不同,因为首先来说,我在公司是 Android 组负责人,属于上述血泪史中催死人不偿命的客户端阵营. 但血泪史却是相通的,没有自动化文档的日子,对接口就是开发流程中最低效的环节. 因此决定使用 swagger 搭建由php注释生成文档的流程. 背景: 我们的 restful api 项目采用 phalcon 框架,整体结构很简单,我们只需要用 swagger 扫描 controller 目录即可. 下简称我们的 php api 项目为 php_api_project. 服务器采用 nginx. 搭建: 先说下最终的文档生成流程会是什么样子,以便先有个整体的认识: 搭建完成后, 整个流程, 从文档生成到前端展现, 大体如下: 在php文件中写 swagger 格式的 /** 注释 */ 用 swagger-php 内的 bin/swagger.phar 命令扫描 php controller 所在目录, 生成 swagger.json 文件 将 swagger.json 文件拷贝到 swagger-ui 中 index.html 指定的目录中 打开 swagger-ui 所在的 url, 就可以看到文档了. 文档中的各个 api 可以在该网址上直接访问得到数据. 实现此需求只需要 swagger 的如下两个项目: swagger-php: 扫描 php 注释的工具. 内含一个不错的例子. swagger-ui: 用以将扫描工具生成的 swagger.json 文件内容展示在网页上. 首先将这两个项目下载到本地: $ git clone https : //github.com/swagger-api/swagger-ui.git $ git clone https : //github.com/zircote/swagger-php.git 文档生成工具部署: 说是部署,主要就是产生 bin/swagger 这个用来生成 swagger.json 文件的命令. 主要工作,就是用 composer 解决下依赖就可以了. 因为国内直接用 composer 比较蛋疼,所以最好设置下国内的那个 c...
评论