直接用phpdocumentor生成rest文档会失败，因其仅解析phpdoc注释，不识别路由、http方法及openapi注释（如@oa\get），需改用zircote/swagger-php并手动补全规范注释。
为什么直接用 phpdocumentor/phpdocumentor 生成 REST 文档会失败
因为 phpdocumentor/phpdocumentor 只解析 PHPDoc 注释，不理解路由定义、HTTP 方法、请求/响应结构。它把 @OA\Get 当普通注释，根本不会渲染成 OpenAPI 节点——除非你手动补全所有 @OA\ 标签，且确保它们在类/方法作用域内被正确识别。
常见错误现象：phpdoc 命令跑完只输出空 api.json 或报错 Could not find any @OA annotations。
- 别把 OpenAPI 注释写在控制器构造函数里——
phpdocumentor不扫描构造函数 - 确保每个接口方法都有
@OA\Get/@OA\Post等顶层注释，且紧跟在/**后面，中间不能插其他注释 - 如果用了 trait 引入方法，OpenAPI 注释必须复制到实际调用该方法的控制器中，不能只放在 trait 里
用 zircote/swagger-php 替代 phpdocumentor 的关键配置
zircote/swagger-php 是专为 OpenAPI 设计的注释驱动生成器，它不要求你写完整 YAML，但强制要求注释结构严格符合 OpenAPI 3.0 规范。它和 Composer 集成顺畅，但默认不自动扫描整个项目——你得告诉它从哪开始扫。
典型 swagger.php 入口脚本：
#!/usr/bin/env php
<?php require __DIR__ . '/vendor/autoload.php';
use OpenApi\Generator;
$openapi = Generator::scan([
'src/Controller',
'src/Entity'
], [
'pattern' => '/\.php$/',
'exclude' => ['/tests/', '/vendor/']
]);
file_put_contents('public/openapi.json', $openapi->toJSON());
-
Generator::scan()第一个参数是路径数组，必须精确到含注释的 PHP 文件目录，不能只写src -
exclude里用正则路径匹配，不是 glob 模式；/tests/末尾斜杠不能省，否则可能漏排除 - 如果
src/Entity里有@OA\Schema注释，必须显式加入扫描路径，否则模型定义不会被引用
在 Slim 或 Laminas 中让路由与 @OA 注释自动对齐
框架路由定义（如 $app->get('/users', [UserController::class, 'list'])）和 OpenAPI 注释是两套系统，不自动同步。你得靠约定或工具桥接：要么把路由路径硬编码进 @OA\Get(path="/users")，要么用反射读取框架路由表再注入注释——后者太重，不推荐。
更可行的做法：
- 所有
@OA\*注释里的path必须和实际注册的路由完全一致，包括 trailing slash（/users/≠/users） - 用
@OA\Tag给控制器加标签，比如@OA\Tag(name="User", description="用户管理接口")，然后在路由注册时保持命名一致，方便后期人工核对 - 避免动态路由参数写法差异：Slim 支持
/users/{id}，Laminas 用/users/:id，而@OA\Get只认{id}形式，所以必须统一用{id}并在框架层做适配
生成文档后发现 401 和 404 响应没出现
OpenAPI 默认只生成成功响应（200），错误码得显式声明。很多人以为框架中间件自动处理了错误响应，其实 swagger-php 完全不知道中间件存在。
必须手动补全常见错误响应：
@OA\Response(
response="401",
description="未认证",
@OA\JsonContent(ref="#/components/schemas/Error")
),
@OA\Response(
response="404",
description="资源不存在",
@OA\JsonContent(ref="#/components/schemas/Error")
)
-
Errorschema 必须提前定义在某个@OA\Schema注释里，且路径能被Generator::scan()扫到 - 不要用
@OA\Response(response=401, ...)—— 数字会被转成字符串，但 OpenAPI 规范要求 key 是字符串，所以写"401"更稳妥 - 如果项目用 JWT，还得加
@OA\SecurityScheme定义BearerAuth，否则 Swagger UI 里无法测试带 token 的请求
自动化程度有限，核心还是靠人写准注释。最易忽略的是：路径参数、查询参数、请求体模型三者类型必须和实际代码一致，否则生成的文档会误导前端——而这种不一致，swagger-php 本身不校验。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
