本文目录导读：
- 方案一：使用 Swagger-PHP（OpenAPI 标准）—— 推荐
- 方案二：仅用 phpDocumentor + 接口风格注释（轻量级）
- 方案三：集成到框架（以 Laravel 为例）
- 方案四：使用 ApiGen / Scribe（适用于 Laravel 的 API 生成器）
- 总结建议
为 PHP 项目生成接口文档，最主流的方案是通过 PHPDoc 风格的注释，配合专门的文档生成工具来自动解析并生成可视化的 API 文档。
以下是几种常用的实现方式,从手动到自动化，以及对应的工具和实践步骤。
使用 Swagger-PHP（OpenAPI 标准）—— 推荐
这是目前最主流、社区最活跃的方式，它通过扩展 PHPDoc 注释，引入 Swagger/OpenAPI 规范注解，生成标准的 openapi.json 文件，然后配合 Swagger UI 渲染出漂亮的接口文档。
安装
composer require zircote/swagger-php
在控制器/路由中添加注解
在控制器的方法上方写注释,使用 #[OA] 属性注解（PHP 8+）或 @OA 注解（PHP 7+）。
示例（PHP 8 属性语法，推荐）：
use OpenApi\Attributes as OA;
class UserController
{
#[OA\Get(
path: "/api/users/{id}",
summary: "获取用户详情",
tags: ["用户管理"],
parameters: [
new OA\Parameter(
name: "id",
in: "path",
required: true,
schema: new OA\Schema(type: "integer")
)
],
responses: [
new OA\Response(
response: 200,
description: "成功返回用户信息",
content: new OA\JsonContent(ref: "#/components/schemas/User")
),
new OA\Response(response: 404, description: "用户不存在")
]
)]
public function show(int $id) {
// ... 业务逻辑
}
}
定义数据模型（Schema）
创建一个新的 PHP 类来描述数据结构，这是让文档内容更清晰的关键。
use OpenApi\Attributes as OA;
#[OA\Schema(schema: "User")]
class User
{
#[OA\Property(type: "integer", example: 1)]
public int $id;
#[OA\Property(type: "string", example: "张三")]
public string $name;
#[OA\Property(type: "string", format: "email", example: "[email protected]")]
public string $email;
}
生成文档文件
在项目根目录创建脚本或使用命令行：
# 扫描 ./app 目录下的所有PHP文件，生成 openapi.json 到 ./public 目录 vendor/bin/openapi app -o public/openapi.json
可视化展示
你需要一个 Swagger UI 来渲染这个 JSON 文件。
- 方式A：下载 Swagger UI，将
dist文件夹放在public/，修改index.html中的url指向你的openapi.json。 - 方式B：使用现成的库（如在 Laravel 中使用
darkaonline/l5-swagger，在 ThinkPHP 中有对应扩展）。 - 方式C：在线 Swagger Editor，直接粘贴
openapi.json内容查看。
仅用 phpDocumentor + 接口风格注释（轻量级）
如果你不想引入复杂的 Swagger 注解，只是把接口说明写在普通 PHPDoc 里，可以使用 phpDocumentor 生成 HTML 文档，它会列出所有类的属性和方法注释。
步骤：
- 安装：
composer require --dev phpdocumentor/phpdocumentor - 写标准 PHPDoc：
/**
- 用户管理接口
- @package Api
*/
class UserController {
/**
- 获取用户列表
- @api GET /api/users
- @param int $page 页码
- @param int $limit 每页数量
- @return array 用户列表数据 */ public function list(int $page = 1, int $limit = 20) { ... } }
- 生成：
vendor/bin/phpdoc -d app/ -t docs/ - 打开
docs/index.html。
缺点：无法像 Swagger 那样直接提供“在线测试接口”的功能，主要用于阅读类和方法说明。
集成到框架（以 Laravel 为例）
安装专门包
composer require darkaonline/l5-swagger php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
修改配置
在 config/l5-swagger.php 中配置 scan 路径（通常是 app/Http/Controllers）。
写注解
同样使用上面方案一的 #[OA] 属性注解，写在控制器和方法上。
生成文档
php artisan l5-swagger:generate
访问
默认访问 http://yourhost/api/documentation，即可看到带 Swagger UI 的文档页面，可直接在页面点击“Try it out”测试接口。
使用 ApiGen / Scribe（适用于 Laravel 的 API 生成器）
- Scribe（推荐 Laravel）：它会自动提取路由、请求验证规则、模型转换等，生成 Markdown 或 Postman 集合。
composer require --dev knuckleswtf/scribe php artisan scribe:generate
它支持从 FormRequest 自动提取字段验证规则，从 API Resource 提取返回字段，非常方便。
总结建议
| 你的需求 | 推荐工具 |
|---|---|
| 需要标准、规范、可可视化调试 | Swagger-PHP (zircote/swagger-php) + Swagger UI |
| 使用 Laravel 且想要省事 | L5-Swagger 或 Scribe |
| 只需要简单的方法和参数说明，不追求在线测试 | phpDocumentor |
| 传统 ThinkPHP / Yii 项目 | 手动写 Swagger 注解，配合 Swagger UI 渲染 |
最佳实践：
- 统一注解风格：项目内统一使用 PHPDoc 的
@param、@return或 Swagger 的#[OA]属性，不要混用。 - 利用 Schema：把数据结构单独定义成类，便于复用和维护。
- 自动化集成：将生成文档的命令加入到 CI/CD 流程（如 Git Hook）中，确保文档随代码更新。
- 敏感信息处理：生产环境中不要暴露
/api/documentation路由，或添加访问权限控制。
如果你是刚开始,建议从 zircote/swagger-php 开始，它的注解语法简洁，且兼容 PHP 7/8，生成的标准 OpenAPI JSON 可以被几乎所有 API 工具（Postman、Apifox、YApi）导入。
