Swagger注解不生效需确认工具链正确：安装zircote/swagger-php而非仅Swagger UI，注解须置于PHPDoc块内紧贴元素，路径需与实际路由一致，显式声明参数，配置servers字段，扫描时指定准确目录并处理权限与编码问题。
PHP 项目里 Swagger 注解不生效？先确认是否装对了工具链
Swagger（现叫 OpenAPI）本身不直接解析 PHP 注解，php-swagger 或 zircote/swagger-php 这类库才是实际干活的。常见错误是只装了 Swagger UI，却没在 PHP 侧生成 JSON/YAML 文件——结果浏览器打开 UI 就报 Failed to load spec。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用 Composer 安装官方推荐的
zircote/swagger-php：运行composer require zircote/swagger-php - 别用过时的
swagger-php（无命名空间老版本），它不兼容 PHP 8+ 的属性语法 - 生成命令不是
swagger命令行（那是 Node.js 版），而是 PHP 脚本调用OpenApi\scan() - 注解必须写在 PHPDoc 块里，且紧贴类、方法或参数上方，中间不能空行
用 @OA\Get 写接口时，路径和参数怎么对应上？
很多人写了 @OA\Get(path="/users")，但路由实际是 /api/v1/users，导致文档路径和真实接口错位。Swagger 不自动读取框架路由配置，所有路径、方法、参数都得手动对齐。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
-
path值必须和你最终暴露给前端的 URL 完全一致，包括前缀（如/api/v1） - 查询参数用
@OA\Parameter显式声明，别指望从函数签名自动提取——function index($id)不会自动生成id参数文档 - 如果用 Laravel/Slim 等框架，
name字段要和$request->getQueryParam('page')里的键名严格一致 - Body 参数（如 JSON 提交）必须用
@OA\RequestBody+@OA\JsonContent描述结构，光写@OA\Property没用
生成的 openapi.json 里没有服务器地址？
生成的文档默认不带 servers 字段，Swagger UI 就不知道该往哪发请求。测试时点 “Try it out” 直接 404，不是后端问题，是文档缺配置。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在任意一个 PHPDoc 块顶部加
@OA\Info，再嵌套@OA\Server，例如：@OA\Info( title="My API", version="1.0.0", @OA\Server(url="https://api.example.com/v1") ) - 开发环境建议写成变量，比如
@OA\Server(url="http://localhost:8000/api")，上线前批量替换 - 多个环境（dev/staging/prod）不要硬编码，改用环境变量注入，避免文档生成脚本里混入敏感地址
Laravel 项目里注解被自动过滤？检查 scan() 的路径范围
很多 Laravel 用户把注解放在 app/Http/Controllers，但执行 OpenApi\scan('app') 却扫不出——因为 scan() 默认跳过 vendor 和隐藏文件，但某些 Laravel 配置会让它误判整个 app 目录为“不可读”。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 显式指定控制器目录：
OpenApi\scan(['app/Http/Controllers'])，别扫太宽 - 确保 PHP 进程有权限读取这些文件（尤其是用 Docker 时，宿主机和容器内 UID 不一致会导致扫描静默失败）
- 注解里别用中文字符串做
description，某些旧版zircote/swagger-php会因 UTF-8 编码问题崩溃，先用英文占位 - 生成脚本里加异常捕获：
try { $openapi = OpenApi\scan(...); } catch (\Exception $e) { die($e->getMessage()); }，不然失败没提示
最常被忽略的一点：注解语法看似简单，但 @OA\Tag 必须和 @OA\Get 在同一个 PHPDoc 块里才生效；拆成两个 /** */ 块，标签就丢了。
