必须同时安装Swagger Plugin和PHP Annotations插件并重启IDE，且项目需含zircote/swagger-php依赖、文件被识别为OpenAPI Specification类型，三者缺一不可，否则无注解高亮与参数补全。
安装 Swagger Plugin 和 PHP Annotations 插件
PHPStorm 本身不内置 Swagger 支持，必须手动安装两个配套插件才能获得注解提示和文档预览能力。缺一不可，否则 @OA\Get 这类注解不会高亮，也无参数补全。
- 打开
File → Settings → Plugins（macOS 是PhpStorm → Preferences → Plugins） - 在搜索框中依次输入并安装：
Swagger Plugin（官方名：SwaggerHub API Design by SmartBear）和PHP Annotations - 安装后重启 IDE —— 不重启的话，已打开的 PHP 文件里注解仍不会触发补全
项目中必须有 zircote/swagger-php 依赖
插件只是“看懂”注解的翻译器，它依赖项目实际引入了 zircote/swagger-php 库。没有这个包，@OA\ 命名空间会标红，补全菜单为空。
- 运行
composer require --dev zircote/swagger-php安装到vendor/ - 确保你的 PHP 文件顶部有
use OpenApi\Annotations as OA;或使用完全限定名（如@OA\Get） - 如果用了自定义命名空间别名（比如
use OpenApi\Annotations as SWG;），插件默认不识别@SWG\Get，得手动配置注解前缀（见下一条）
启用 OpenAPI Specification 文件类型识别
要让 YAML/JSON 格式的 OpenAPI 文档获得语法校验、路径跳转、引用补全等能力，IDE 必须把这类文件识别为专用文件类型。
- 新建文件时，右键项目根目录 →
New → OpenAPI Specification，选择OpenAPI 3.0 (YAML)等模板 - 若已有
openapi.yaml文件但没被识别：右键该文件 →Override File Type → OpenAPI Specification - 验证是否生效：打开文件，光标放在
paths:下，按Alt+Insert应出现 gutter 图标（小加号），点击可快速插入get/post等区块
预览 OpenAPI 文档需要额外配置
PHPStorm 自带的 OpenAPI 预览功能（类似 Swagger UI 的简易渲染）默认不启用，且仅支持本地 YAML/JSON 文件，不代理后端接口。
立即学习“PHP免费学习笔记（深入）”；
- 确保文件是
.yaml或.json后缀，并已被识别为OpenAPI Specification类型 - 打开该文件，在编辑器右上角点击
Preview标签页（若没看到，检查Settings → Languages & Frameworks → OpenAPI Specifications中是否勾选了Enable preview） - 注意：此预览不执行真实请求，只做结构可视化；想调试接口需配合
OpenAPI Generator生成客户端，或用外部工具如Swagger UI服务托管 JSON
zircote/swagger-php 存在、文件类型被正确识别。漏掉任意一个，你看到的就只是普通文本，而不是可导航、可验证、可生成的 API 规范。 
