必须同时安装Swagger Plugin和PHP Annotations插件并重启IDE，项目需含zircote/swagger-php依赖，且YAML/JSON文件须被识别为OpenAPI Specification类型，三者缺一不可，否则注解不高亮、无参数补全、预览不出现。
Swagger Plugin 和 PHP Annotations 插件必须同时安装
只装 Swagger Plugin 不会识别 @OA\Get，只装 PHP Annotations 也不会高亮注解或补全参数——两者缺一不可。安装后必须重启 IDE，否则已打开的 PHP 文件里注解仍不生效。
在 Settings → Plugins（macOS 是 PhpStorm → Preferences → Plugins）中搜索并安装：
-
Swagger Plugin（官方名：SwaggerHub API Design by SmartBear） PHP Annotations
项目必须有 zircote/swagger-php 且被正确加载
插件只是“翻译器”，没有 zircote/swagger-php，@OA\ 命名空间会标红，补全菜单为空。运行以下命令安装：
composer require --dev zircote/swagger-php
还要确保 PHP 文件中引用了命名空间：
立即学习“PHP免费学习笔记（深入）”；
- 要么顶部写
use OpenApi\Annotations as OA;，然后用@OA\Get - 要么直接用完全限定名
@OA\Get（前提是 autoloader 已加载该类） - 如果用了自定义别名如
use OpenApi\Annotations as SWG;，插件默认不识别@SWG\Get，得手动配置注解前缀
YAML/JSON 文件必须被识别为 OpenAPI Specification 类型
否则没有语法校验、$ref 跳转、路径补全，也打不开预览。判断依据：光标放在 paths: 下按 Alt+Insert 应出现 gutter 小加号。
若已有 openapi.yaml 但没识别：
- 右键文件 →
Override File Type → OpenAPI Specification - 或新建时用
File → New → OpenAPI Specification，选OpenAPI 3.0 (YAML) - 空文件可输入
opnp+Tab插入模板
Preview 标签页不出现？检查 OpenAPI 预览是否启用
预览功能默认关闭，且只支持本地 YAML/JSON 文件，不代理后端接口。打开 Settings → Languages & Frameworks → OpenAPI Specifications，确认勾选了 Enable preview。
打开已识别为 OpenAPI 的文件后，编辑器右上角应出现 Preview 标签页。注意：
- 此预览纯静态渲染，不发真实请求
- 不支持
server.url动态变量，所有路径都按文档字面量解析 - 若内容为空白或报错，先检查 YAML 缩进和冒号后空格——这类格式错误不会高亮，但会导致预览失败
@OA\ 就只是普通字符串。最常被忽略的是重启 IDE 和手动设置文件类型。 
