利用 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() {}

}