phpstorm本身不生成api文档，仅提供phpdoc注释模板、语法校验及外部工具（如phpdocumentor、swagger-php、apidoc）集成能力；真正生成文档需依赖这些工具解析规范注释并输出html或openapi格式。
PhpStorm 本身不生成 API 文档，它只提供注释模板、语法校验和工具链集成能力。真正生成文档的是外部工具（如 phpDocumentor、swagger-php 或 apidoc），PhpStorm 的作用是帮你写对注释、配好路径、一键触发命令。
配置 PHPDoc 注释模板（避免手写漏项）
没模板就等于靠人肉记忆写 @param、@return、@throws，极易遗漏或格式错位——后续所有文档工具都依赖这些标签的完整性。
- 路径：
Settings > Editor > File and Code Templates > Includes，重点改两个：PHP File Header（类/文件头） 和PHP Function Doc Comment（函数注释） - 变量大小写敏感：
$DATE$有效，$date$直接失效；$NAME$是当前函数名，$PARAMETERS$自动展开参数列表，别手动写 - 魔术方法默认不触发：如
__invoke()、__toString()，需手动勾选Settings > Editor > Inspections > PHP > PHPDoc > Missing PHPDoc > Treat __invoke as documented method - 闭包、类属性、trait 方法不支持自动生成，得手写
/** @var string $name */这类注释
集成 phpDocumentor（生成 HTML API 文档）
phpDocumentor 是目前最稳定、兼容性最好的 PHP 原生文档生成器，适合内部技术文档交付。它吃的是标准 PHPDoc，不吃自定义标签。
- 安装建议用项目级依赖：
composer require --dev phpdocumentor/phpdocumentor（避免全局版本冲突） - 初始化配置：
./vendor/bin/phpdoc --initialize生成phpdoc.xml，然后手动确认<directory>./src</directory>和<output>docs/api</output> - PhpStorm 内直接调用：在
Settings > Other Settings > PHP > Documentation中填入./vendor/bin/phpdoc路径，再右键目录选Generate PHP Documentation - 注意权限：如果输出目录
docs/api不存在，phpdoc不会自动创建，会静默失败——先mkdir -p docs/api
接入 swagger-php（生成 OpenAPI/YAML 供 Swagger UI 展示）
如果你的 API 要给前端、测试或第三方调用，swagger-php 是更现实的选择。它把 PHPDoc 扩展成 OpenAPI 描述，但要求注释结构更严格。
- 安装：
composer require --dev zircote/swagger-php - 注释必须用
@OA\Get、@OA\Post等命名空间标签，不是传统@api；@OA\Parameter必须显式写in="path"或in="query"，否则解析失败 - 生成命令示例：
./vendor/bin/openapi --bootstrap constants.php -o openapi.yaml ./src/Controller；--bootstrap用于加载常量或配置，否则@OA\Info里的version可能为空 - PhpStorm 不识别
@OA\*标签的语义，仅当作文本高亮——所以拼写错误（比如@OA\Reponse）不会报错，但会导致openapi.yaml生成失败或字段缺失
为什么 apidoc 在 PhpStorm 里容易出问题
apidoc 是基于 Node.js 的工具，和 PHP 生态松耦合。它不读 PHPDoc，而是靠自己定义的一套 @api 注释语法，和 PhpStorm 的 PHP 解析器完全不兼容。
- PhpStorm 对
@api、@apiParam零支持：没有语法高亮、无补全、无法跳转，写错一个字母也不会提示 - 注释位置极其敏感：必须紧贴函数声明上方，中间不能有空行；
@apiName值不能含空格（@apiName user login→ 解析失败） - 路径指定要绝对谨慎：
apidoc -i app/Http/Controllers -o public/doc，若-i指向了含非 PHP 文件的目录（如.git或node_modules），会卡住或报Unexpected token ILLEGAL - 它不解析命名空间或
use语句，所有类型都得手写字符串，比如@apiParam {User} user，而User类是否真实存在，apidoc完全不管
最常被忽略的点：所有工具都依赖「注释块和代码结构严格对齐」。哪怕只是多了一个空格、少了一个星号、@param 类型写成 string|null（而工具只认 string 或 mixed），生成结果就可能空白或字段丢失。别信“写了就能出”，每次改完注释，务必跑一遍生成命令看输出是否真包含你想要的内容。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
