pkg6 / apidoc
Generate documentation for php API based application. No dependency. No framework required.
v0.1.0
2025-05-25 12:58 UTC
Requires
- php: >=5.4
- ext-json: *
This package is auto-updated.
Last update: 2025-06-04 01:50:37 UTC
README
为基于 PHP 的 API 应用生成文档 无需依赖框架,无需额外依赖。
📋 环境要求
- PHP >= 5.3.2
📦 安装
使用 Composer 安装:
composer require pkg6/apidoc
🚀 使用方法
在你的类和方法上使用注解:
namespace Pkg6\Apidoc\Tests\TestClasses;
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")
* @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="年龄")
*/
public function create() {}
}
⚙️ 生成 API 文档
<?php
use Pkg6\Apidoc\Builder;
require 'vendor/autoload.php';
$classes = array(
"Pkg6\Apidoc\Tests\TestClasses\User",
"Pkg6\Apidoc\Tests\TestClasses\Article"
);
$output_file = 'api.html'; // defaults to index.html
try {
$builder = new Builder($classes, ".", 'Api Title', $output_file);
$builder->generate();
} catch (Exception $e) {
echo 'There was an error generating the documentation: ', $e->getMessage();
}
然后通过命令行执行该文件:
php apidoc.php
生成的API文档将保存在 api.html
。
🧩 支持的注解方法
目前支持以下注解:
@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="...")
💡 小技巧
如果你希望展示复杂对象的输入示例,可以使用 @ApiParams
并设置 type=object|array|array(object)
,例如:
@ApiParams(
name="data",
type="object",
sample="{'user_id':'int','profile':{'email':'string','age':'integer'}}"
)
🙏 感谢
本项目灵感来源并参考了优秀的开源项目 calinrada/php-apidoc,在此致以诚挚感谢 🙌。