利用 phpapidoc 自动生成 api 文档

相信不少码农做过 api 的开发，可能好不容易完成功能后，满以为可以悠哉了去看妹子，结果经理来了一句把 api 文档也写了吧。 wtf！最讨厌写文档了，然后又打开代码，慢慢的一个一个对照写文档，质量可想而知。

前段时间罗飞老师在讲 api 分层构建的时候提到开发 api 的几个方面，其中一个就是 API 文档自动生成机制，试想如果在编写代码的同时，可以直接通过某种方式把这个 api 也描述清楚，最终只要执行某个脚本就可以自动生成 api 文档，clean and fast~

php-apidoc 就是这样一个自动化的 api 生成工具，使用 php 编写，只需要在方法的注释里加上相应的规则即可，原理是通过 php 的反射机制动态获取 annotation, 然后做相应处理.

## 安装

推荐使用 composer 安装，把下面的代码加入到 composer.json 中，同时为了测试另外在项目根目录下建立一个 src 目录，里面放一个 user.php 文件采用 psr-4 加载。所以最终 composer.json 代码如下。

{
    "require": {
    "crada/php-apidoc": "@dev",
    	"autoload": {
    		"psr-4": {
    			"Acme\\": "src/"
    		}
    	}
    }
}

执行 composer update 即可

## 使用

假设我们要开发一个 user 的 api 接口，使用 rest 风格，对应的 crud 方法如下:

<?php

class User
{
	//用于获取id为$id的用户信息
	public function get($id) {}

	//创建用户
	public function create() {}

	//更新用户
	public function update() {}

	//删除用户
	public function delete() {}
}

然后准备一个入口文件作为执行脚本，这里建立一个 index.php 文件

<?php


use Crada\Apidoc\Builder;
use Crada\Apidoc\Exception;

require "vendor/autoload.php";

$classes = array(
    'Acme\\User'
);

$ouput_dir = __DIR__ . '/apidocs';


try {
    $builder = new Builder($classes, $ouput_dir, '接口文档V1.0', 'api.html');
    $builder->generate();
} catch (Exception $e) {
    echo "error ", $e->getMessage();
}

执行后在 apidocs 目录下回生成一个 api.html 访问如图：

api 方法怎么木有？这不是坑爹吗。。

别急，接下来我们来开始写 api 对应的方法。

官方提供的一些方法如下

@ApiDescription: 定义某个接口的描述其中 section 参数作为分组，description 作为描述
@ApiMethod: 定义接口的请求方法，参数为 type, 可选值有 get|post|put|delete
@ApiRoute: 定义接口请求地址参数为 name

以上三个为必填项

接下来有一些可选方法
定义请求参数: @ApiParams(name="...", type="...", nullable=..., description="...", [sample=".."])
定义请求头: @ApiHeaders(name="...", type="...", nullable=..., description="...")
定义响应头: @ApiReturnHeaders(sample="...")
定义响应结果: @ApiReturn(type="...", sample="...", [description="..."])

其中参数的 type 类型可以是 'object', 'array(object) ', 'array', 'string', 'boolean', 'integer', 'number'

<?php

namespace Acme;

class User
{
    /**
     * @ApiDescription(section="User", description="获取用户信息")
     * @ApiMethod(type="get")
     * @ApiRoute(name="/user/get/{id}")
     * @ApiParams(name="id", type="integer",nullable=false,description="用户id")
     * @ApiParams(name="data", type="object",sample="{'user_id': 'int', 'user_name':'string','profile':{'email':'string','age':'integer'}}")
     * @ApiReturnHeaders(sample="HTTP 200 OK")
     * @ApiReturn(type="object", sample="{
     *     'transaction_id' : 'int',
     *     'transaction_status': 'string'
     * }")
     */
    public function get() {}

    /**
     * @ApiDescription(section="User", description="创建用户")
     * @ApiMethod(type="post")
     * @ApiHeaders(name="header_key", type="string", nullable=true, description="test_header_key")
     * @ApiRoute(name="/user/create")
     * @ApiParams(name="username", type="string", nullable=false, description="用户名")
     * @ApiParams(name="email", type="string", nullable=false, description="邮箱")
     * @ApiParams(name="password", type="string", nullable=false, description="密码")
     * @ApiParams(name="age", type="integer", nullable=true, description="年龄")
     * @ApiReturn(type="object",sample="{'user_id':'int','profile':{'email':'string','age':'integer'}}", description="用户信息")
     */
    public function create() {}

    /**
     * @ApiDescription(section="User", description="更新用户")
     * @ApiMethod(type="put")
     * @ApiRoute(name="/user/update")
     * @ApiParams(name="id", type="integer", nullable=false, description="用户ID")
     * @ApiReturn(type="boolean",sample=true, description="用户更新结果")
     */
    public function update() {}

    /**
     * @ApiDescription(section="User",description="删除用户")
     * @ApiMethod(type="delete")
     * @ApiRoute(name="/user/delete")
     * @ApiParams(name="id", type="integer", nullable=false, description="用户ID")
     * @ApiReturn(type="boolean",sample=true, description="用户删除结果")
     */
    public function delete() {}

}