PHP项目应使用注解（如zircote/swagger-php或nelmio/api-doc-bundle）自动生成OpenAPI文档，注解须写在可自动加载的类/方法中，严格遵循OpenAPI v3规范定义请求体、响应体及MIME类型，并通过PHP路由动态输出JSON以适配Swagger UI/Redoc。
PHP 项目里不写 YAML 怎么生成 OpenAPI 文档
靠手写 openapi.yaml 维护 API 文档，基本等于放弃更新。PHP 项目真正可行的路，是用注解（annotations）在代码里写文档，再用工具扫描生成标准 OpenAPI JSON/YAML。核心不是“用不用 Swagger”，而是选对能和 PHP 类型系统、框架生命周期对齐的解析器。
主流选择只有两个：zircote/swagger-php（老牌，兼容性好）和 nelmio/api-doc-bundle（Symfony 专用，开箱即用）。Laravel 用户别硬套 zircote，它不识别 @OA\Get 在 Laravel 路由闭包里的上下文，会漏掉大量 endpoint。
-
zircote/swagger-php必须配合phpdocumentor/reflection-docblockv5+，旧版 PHP 7.4 项目容易因反射类版本冲突导致注解全失效 - 注解必须写在「可被自动加载」的类/方法上——控制器方法、API Resource 类、甚至 DTO 的属性都行；写在普通函数或未 use 的 trait 里，扫描器直接跳过
- 不要在注解里写动态值，比如
@OA\Property(property="id", type="{{ $type }}")，解析器只认字面量字符串，变量、常量、环境判断一律不展开
PHP 注解里怎么写请求体和响应体才不翻车
90% 的文档生成失败，卡在 @OA\RequestBody 和 @OA\Response 的 content 结构没对齐实际返回。OpenAPI v3 要求明确指定 MIME 类型，且 schema 必须可递归解析——PHP 数组、stdClass、Eloquent 模型都不能直接塞进去。
正确做法是用 @OA\Schema 显式定义结构，再通过 ref 或 allOf 复用。比如 Eloquent 模型字段多，别手写所有 @OA\Property，改用 @OA\Schema(ref="#/components/schemas/User")，然后在 @OA\Components 里单独定义 User schema。
立即学习“PHP免费学习笔记（深入）”；
- 请求体如果是
application/json，@OA\RequestBody的required字段必须和@OA\Schema的required数组严格一致，少一个就标红报错 - 响应状态码别只写
@OA\Response(response="200", ...)，OpenAPI 规范要求每个 response 至少带description，否则生成的 YAML 会缺字段，部分 UI 渲染器直接空白 -
@OA\Property的type值只能是 OpenAPI 官方类型（string、integer、boolean、array、object），不能写 PHP 类型如int或array|null
生成的文档 JSON 怎么接入 Swagger UI 或 Redoc
生成出来的 openapi.json 不是终点，是静态资源。它得能被 HTTP 直接访问，且响应头 Content-Type 必须是 application/vnd.oai.openapi+json;version=3.0.0 或至少 application/json。Nginx/Apache 默认不认 .json 后缀为 JSON，会返回 text/plain，Swagger UI 就报 “Failed to load spec”。
最稳的方式：用 PHP 路由动态输出 JSON，而不是放静态文件。Laravel 可加一条路由 Route::get('/docs/openapi.json', [DocsController::class, 'openapi'])，控制器里 return response($json, 200)->header('Content-Type', 'application/vnd.oai.openapi+json;version=3.0.0');。
- Swagger UI 加载时默认发 OPTIONS 预检，如果后端没配 CORS，控制台会报 CORS 错误，但 UI 只显示 “Unable to render this definition”，要查 Network 面板看预检是否 403
- Redoc 支持直接传 URL，但要求该 URL 可跨域访问；如果用
file://协议打开本地 HTML，现代浏览器直接拒绝加载远程 JSON - 生成的 JSON 文件体积超过 1MB，某些 Swagger UI 版本（v4.15 之前）会卡死，建议用
swagger-php的--quiet参数减少冗余注释
为什么 PHPStorm 里注解没提示、跳转也不生效
不是插件问题，是 PHPStorm 的 stubs 和注解索引没覆盖 @OA\*。它默认只认 PHPDoc 标准标签（@param、@return），@OA\Get 这种自定义标签需要手动注册。
进 Settings → Editor → Inspections → PHP → PHPDoc，勾选「Unknown PHPDoc tag」并设为 Warning；再装插件 PHP Annotations（JetBrains 官方维护），重启后就能补全 @OA\ 前缀和参数。
- 装完插件仍无提示？检查项目根目录有没有
phpstorm.meta.php或.phpstorm.meta.php，这类文件会覆盖插件的默认映射，删掉再试 - 注解跳转到
Schema类报 “Cannot find declaration”，说明zircote/swagger-php的 vendor 文件没被索引，右键 vendor → “Mark as Sources” - PHPStorm 2023.3+ 对 PHP 8.2 的只读属性（
readonly）支持不全，如果 DTO 用了readonly public string $name;，注解里的@OA\Property可能无法关联类型推导
最难调的其实是注解嵌套层级——比如 @OA\Schema 里套 @OA\Items 再套 @OA\Schema，中间漏一个 ref 或多一个 type="object"，整个结构就崩，但错误提示只说 “Invalid schema”，得一层层缩进检查。这种地方没法偷懒，只能打开生成的 JSON，对照 OpenAPI Spec 逐字段比对。
