README

为基于 PHP API 的应用程序生成文档。无需依赖。无需框架。

• 要求
• 安装
• 使用方法
• 可用方法
• 预览
• 提示
• 已知问题
• 待办事项

要求

PHP >= 5.3.2

安装

建议使用 composer 进行安装。只需将以下行添加到您的 composer.json 文件中

{
    ...
    "require": {
        ...
        "crada/php-apidoc": "@dev"
    }
}

$ php composer.phar update

使用方法

<?php

namespace Some\Namespace;

class User
{
    /**
     * @ApiDescription(section="User", description="Get information about user")
     * @ApiMethod(type="get")
     * @ApiRoute(name="/user/get/{id}")
     * @ApiParams(name="id", type="integer", nullable=false, description="User 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="Create's a new user")
     * @ApiMethod(type="post")
     * @ApiRoute(name="/user/create")
     * @ApiParams(name="username", type="string", nullable=false, description="Username")
     * @ApiParams(name="email", type="string", nullable=false, description="Email")
     * @ApiParams(name="password", type="string", nullable=false, description="Password")
     * @ApiParams(name="age", type="integer", nullable=true, description="Age")
     */
    public function create()
    {

    }
}

在项目根目录下创建一个名为 apidoc.php 的文件，如下所示

# apidoc.php
<?php

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

$classes = array(
    'Some\Namespace\User',
    'Some\Namespace\OtherClass',
);

$output_dir  = __DIR__.'/apidocs';
$output_file = 'api.html'; // defaults to index.html

try {
    $builder = new Builder($classes, $output_dir, 'Api Title', $output_file);
    $builder->generate();
} catch (Exception $e) {
    echo 'There was an error generating the documentation: ', $e->getMessage();
}

然后，通过 CLI 执行它

$ php apidoc.php

可用方法

以下是目前可用的方法列表

• @ApiDescription(section="...", description="...")
• @ApiMethod(type="(get|post|put|delete|patch")
• @ApiRoute(name="...")
• @ApiParams(name="...", type="...", nullable=..., description="...", [sample=".."])
• @ApiHeaders(name="...", type="...", nullable=..., description="...")
• @ApiReturnHeaders(sample="...")
• @ApiReturn(type="...", sample="...")
• @ApiBody(sample="...")

预览

您可以在 http://calinrada.github.io/php-apidoc/ 上查看生成的示例文档

提示

要生成复杂对象示例输入，请使用 ApiParam "type=(object|array(object)|array)"

* @ApiParams(name="data", type="object", sample="{'user_id':'int','profile':{'email':'string','age':'integer'}}")

已知问题

我不知道任何，但如果你发现了什么，请告诉我。PS：我仅在 Chrome 中进行了测试！

待办事项

• 实现 JSONP 选项
• 实现 "添加字段" 选项