@OA\Get 不生效主因是扫描范围或加载上下文错误：Swagger-PHP 仅解析 Composer 自动加载的类；闭包路由、注解与方法间空行、PHP 版本/反射扩展不兼容、path 缺失开头 / 均会导致失效。
Swagger-PHP 注解生成 OpenAPI 文档，但 @OA\Get 不生效？
不是注解写错了，大概率是扫描范围或加载上下文没对上。Swagger-PHP 默认只解析「能被 Composer 自动加载」的类文件，控制器方法如果没被 autoload 覆盖（比如写在非 PSR-4 规范路径、或用了动态 include），就直接跳过。
常见卡点：
-
@OA\Get写在闭包路由里 —— Laravel 或 ThinkPHP 的闭包定义不进反射，必须移到控制器方法中 - 注解块和方法之间有空行或其它注释 ——
/** */必须紧贴方法声明上方，中间不能隔任何东西 - PHP 版本低于 7.4 或反射扩展版本冲突 ——
zircote/swagger-phpv4 要求phpdocumentor/reflection-docblockv5+，旧项目升级时容易漏掉 - 路径写成
path="users"而不是path="/users"—— OpenAPI 规范强制要求绝对路径，漏掉开头/会导致 Swagger UI 拼接 base_url 失败
ApiGen 生成空白页面或报错 Class not found？
ApiGen 已停止维护（最后发布于 2019 年），它依赖老旧的 PHP 解析器，对 PHP 8+ 的联合类型、属性提升、命名空间别名等语法支持极差。你看到的「空白」或「Class not found」，往往是解析器在 AST 阶段就崩溃了，没抛出明确异常，只默默跳过文件。
替代建议：
立即学习“PHP免费学习笔记（深入）”；
- 改用
phpdocumentor/phpdocumentor（v3+），它基于现代 PHP-Parser，支持 PHP 8.2+ 和全部新语法 - 命令行参数要显式指定编码和源码目录：
phpdoc project:run -d src/ -t docs/api --encoding=utf8 - 确保每个类/方法都有完整
@param和@return—— ApiGen 类似工具对缺失标签极其敏感，缺一个就可能整块不渲染
想绕过注释，靠类型声明自动生成文档？
PHP 8+ 的原生类型（string、int、User|null）和属性（#[OA\Property]）确实能减少注释量，但工具链还没完全跟上。目前只有 zircote/swagger-php v4+ 支持 PHP 8 属性语法，且仅限于顶层类或方法，不能自动推导嵌套数组结构（如 array<user></user>）。
实际能省力的地方有限：
-
function getUser(int $id): User→@OA\Parameter和@OA\Response仍需手动写，类型不会自动转成 schema -
#[OA\Schema]必须显式定义字段，不能靠public User $user;反射出 User 的全部属性 - DTO 类里写了
public string $name;，仍得补#[OA\Property(type: "string")]，否则字段不出现在文档里
CI/CD 中自动生成文档并部署，关键在哪？
不是脚本能不能跑通，而是文档产物是否可复现、可验证。很多团队卡在「本地能生成，CI 里失败」，本质是环境差异没对齐。
必须检查的三件事：
- CI 环境的 PHP 版本、扩展（特别是
mbstring、json、tokenizer）要和本地一致，php -m对一遍 - 生成命令必须带
--no-interaction和明确输出路径，避免因交互式提示卡住；例如：vendor/bin/openapi --output public/openapi.json --spec-version 3.1.0 src/ - 生成的
openapi.json要加到 CI 后置校验：用jq检查是否存在paths字段、info.title是否非空，防止静默生成空文件
最易忽略的是文档中引用的外部 schema（如 ref="#/components/schemas/User"），一旦 @OA\Components 定义位置不对或拼写错误，JSON 本身合法但 UI 渲染为空白 —— 这种问题只能靠人工点开生成的 JSON 文件肉眼核对。
