装 zircote/swagger-php 后需三步：配置 Composer autoloader 映射 OpenApi\Annotations 命名空间，用 vendor/bin/openapi 命令生成 openapi.json 到 public/ 目录，再通过 swagger-ui-dist 提供前端 UI 预览。
直接装 zircote/swagger-php 就够了，但别只 run install
装上 zircote/swagger-php 并不等于项目能自动生成 Swagger 文档。它只是个 PHP 注解解析器，本身不带 Web UI、不启动服务、也不自动扫描路由。你得自己配注解位置、加生成命令、再把输出喂给 Swagger UI 或 OpenAPI 工具链。
composer require zircote/swagger-php 后必须手动加 autoloader 配置
默认安装后，@OA\Info、@OA\Get 这类注解不会被自动识别——PHP 不会主动加载注解类，除非你告诉 Composer 哪些命名空间要扫。常见漏配导致报错：Class "OpenApi\Annotations\Get" not found。
- 在
composer.json的"autoload"下加 PSR-4 映射（Swagger-PHP 4.x 要求）：
"autoload": {
"psr-4": {
"App\\": "app/",
"OpenApi\\Annotations\\": "vendor/zircote/swagger-php/src/Annotations/"
}
}
- 运行
composer dump-autoload生效 - 不加这行，哪怕
use OpenApi\Annotations as OA;也救不了 —— 类根本没进自动加载器
生成文档用 vendor/bin/openapi，不是 artisan 或 php serve
Swagger-PHP 提供的是命令行工具 openapi，不是 Laravel 的 php artisan 命令，也不是内置服务器。你得明确指定源码路径、输出格式和目标文件。
- 基础生成命令（假设 API 注解写在
app/Http/Controllers）：
vendor/bin/openapi app/Http/Controllers --output public/openapi.json
- 加
--format yaml输出 YAML（适合 Swagger UI 加载） - 加
--annotations ./config/swagger可额外指定注解配置目录（比如全局@OA\Info单独放） - 别指望它自动读
routes/web.php—— 它只认 PHP 文件里的 PHPDoc 注解
本地预览需额外搭 UI，推荐用 swagger-ui-dist
openapi.json 是纯数据，浏览器打不开。得用前端 UI 渲染。最轻量做法是直接引入官方 dist 包：
立即学习“PHP免费学习笔记（深入）”；
- 执行：
composer require --dev swagger-api/swagger-ui-dist - 把
vendor/swagger-api/swagger-ui-dist下的文件复制到public/swagger/ - 在
public/swagger/index.html里改url: "/openapi.json" - 访问
http://your-app.test/swagger/即可交互式查看
注意：如果你用的是 Laravel，别把 openapi.json 放在 resources/ 下——它必须能被 Web 服务器直接 HTTP 访问，所以放 public/ 是唯一靠谱路径。
真正卡住人的地方，从来不是“装没装上”，而是注解没被 autoload 扫到、生成命令没指定对目录、或者生成完忘了配静态资源路径。三步缺一不可，少一步页面就空白或报 404。
