swagger 生成 PHP restful API 接口文档

需求:

为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用自动化文档工具前手写文档的血泪史.

我的故事却又不同,因为首先来说,我在公司是 Android 组负责人,属于上述血泪史中催死人不偿命的客户端阵营.

但血泪史却是相通的,没有自动化文档的日子,对接口就是开发流程中最低效的环节.

因此决定使用 swagger 搭建由php注释生成文档的流程.

背景:

我们的 restful api 项目采用 phalcon 框架,整体结构很简单,我们只需要用 swagger 扫描 controller 目录即可.

下简称我们的 php api 项目为 php_api_project.

服务器采用 nginx.

搭建:

先说下最终的文档生成流程会是什么样子,以便先有个整体的认识:

搭建完成后, 整个流程, 从文档生成到前端展现, 大体如下:

1. 在php文件中写 swagger 格式的 /** 注释 */

2. 用 swagger-php 内的 bin/swagger.phar 命令扫描 php controller 所在目录, 生成 swagger.json 文件

3. 将 swagger.json 文件拷贝到 swagger-ui 中 index.html 指定的目录中

4. 打开 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 比较蛋疼,所以最好设置下国内的那个 composer 源.

这样的话, 整个 文档生成工具的部署 就是下面三行命令:

$ cd swagger-php
$ composer config repo.packagist composer https://packagist.phpcomposer.com
$ composer update

只要中间不报错,就算部署完成了. 完成后可以生成一份文档试一下.

swagger-php 项目下的 Examples 目录下有一个示例php工程,里面已经用 swagger 格式写了各种接口注释, 我们来尝试生成一份文档.

执行下面命令:

$ cd swagger-php
$ mkdir json_docs
$ php ./bin/swagger ./Examples -o json_docs/

上面命令会扫描 Examples 目录中的php文件注释, 然后在 json_docs 目录下生成 swagger.json 文件.

这个 swagger.json 文件就是前端 swagger-ui 用来展示的我们的api文档文件.

NOTE: swagger-php 只是个工具,放在哪里都可以.

前端 swagger-ui 部署: