先确认PHP版本≥7.4且启用json、mbstring扩展；若PHP 7.4则用composer require zircote/swagger-php:^3.4.1，避免v4+版本冲突；检查是否被安全插件拦截，删vendor重装；确保注解写在public方法PHPDoc中并显式扫描对应路径。
composer require zircote/swagger-php 失败怎么办
装不上就别往下走了，90% 的后续问题都根源于这一步卡住。不是“稍后再试”，而是必须当场解决。
- 国内网络下直接
composer require zircote/swagger-php极大概率超时或 404 → 先执行composer config repo.packagist composer https://packagist.phpcomposer.com（注意是phpcomposer.com，不是旧的laravel-china.org） - 用宝塔/AMH 面板 Shell 执行报
HOME or COMPOSER_HOME must be set→ 别在面板里硬刚，SSH 登录服务器后执行 - Windows WSL 或 Docker 环境下
vendor/bin/openapi报 “Permission denied” → 运行chmod +x vendor/bin/openapi - 命令返回 “Successfully installed”，但
vendor/zircote/swagger-php目录不存在 → 检查是否被 Composer 插件拦截（比如某些安全插件会静默跳过），删掉vendor重装
@OA\Get 注解写了却没出现在 swagger.json 里
swagger-php 是静态扫描器，它不运行代码，只读文件。你写的注解“看不见”，基本是路径、可见性或路由三者之一断了链。
- 注解必须写在
public方法的 PHPDoc 块内，private、protected、__invoke、中间件、模型方法里的注释全被忽略 - 控制器命名空间如
app\api\v2\UserController，扫描命令必须显式包含该路径：vendor/bin/openapi app/api/v2/ --output public/openapi.json，别只扫app/controller/ - 路由没真正绑定到该方法 → 检查
route/app.php是否有类似Route::get('api/users', 'api.v2.UserController@list');这样的显式声明；资源路由Route::resource('users', 'UserController')默认不扫描，得加->only(['index', 'show']) - 注解里写的
path="/api/users"必须和实际可访问的 URL 完全一致（包括前缀、大小写、斜杠结尾），否则生成的 JSON 里接口字段为空
嵌套参数 @param array $data 不解析？
ThinkPHP 生态（尤其是 think-swagger 或原生 swagger-php 3.x）对 PHPDoc 的解析非常严格，@param array 这种写法等于没写 —— 它不会递归展开数组结构，也不会识别内部字段类型。
- JSON body 中的嵌套对象（如
{"user": {"name": "a", "age": 18}}）必须扁平化拆解：@param string $user_name、@param int $user_age - URL 查询参数或表单字段中的嵌套（如
filter[status]=1&filter[name]=test）同样不能写@param array $filter，而要写成@param string $filter_status、@param string $filter_name - 如果字段名含点号或中括号（如
user.profile.nick），Swagger UI 可能渲染异常 → 改用下划线风格（user_profile_nick）并配合@OA\Schema的description字段说明原始结构
swagger-ui 打开空白或报 Failed to load API definition
这不是 PHP 错误，而是前端加载失败。Swagger UI 只需要一个合法的 JSON 文件和正确的访问路径，其余全是环境配置问题。
立即学习“PHP免费学习笔记（深入）”；
-
public/openapi.json必须能被 Web 服务器直接 HTTP 访问（例如https://yourdomain.com/openapi.json），不能放在受路由保护或权限限制的目录下 - Apache 用户检查
.htaccess是否拦截了.json后缀（加一行<Files "*.json">Order Allow,DenyAllow from all</Files>） - Nginx 用户确认没有
location ~ \.json$ { deny all; }类规则，且确保openapi.json文件 MIME 类型为application/json（加add_header Content-Type application/json;） - JSON 文件本身必须严格符合 OpenAPI 3.0 规范：字段名大小写敏感（
responses不是Responses），@OA\Response必须带response="200"字符串而非数字，schema必须是对象，不能是空数组
vendor/bin/openapi 生成新 JSON，否则浏览器里看到的永远是旧的、甚至语法错误的内容。 
