必须同时安装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\ 命名空间会标红，补全菜单为空。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• 运行 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 文件，不代理后端接口。

• 确保文件是 .yaml 或 .json 后缀，并已被识别为 OpenAPI Specification 类型
• 打开该文件，在编辑器右上角点击 Preview 标签页（若没看到，检查 Settings → Languages & Frameworks → OpenAPI Specifications 中是否勾选了 Enable preview）
• 注意：此预览不执行真实请求，只做结构可视化；想调试接口需配合 OpenAPI Generator 生成客户端，或用外部工具如 Swagger UI 服务托管 JSON

Swagger 注释补全和文档预览不是开箱即用的功能，最关键的三个条件必须同时满足：插件装对、zircote/swagger-php 存在、文件类型被正确识别。漏掉任意一个，你看到的就只是普通文本，而不是可导航、可验证、可生成的 API 规范。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！