Webman 里用 Swagger 自动生成 API 文档，不是靠“自动发现路由”，而是靠「手动加注释 + 手动扫描目录 + 静态托管 UI」——它不依赖框架反射机制，所以兼容 PHP 7.4+，也适合 Webman 这类轻量级 Swoole 框架。
为什么 Webman 不能像 Laravel 那样一键生成文档
Webman 没有统一的路由注册中心、没有 Route::apiResource() 这类语义化路由定义，route.php 里通常是闭包或控制器方法直连。Swagger-php 不会解析路由文件，它只认 PHPDoc 注释，且必须能加载到对应类/方法的源码。
- 你写的是
get('/user', [UserCtrl::class, 'index'])，但 Swagger-php 看不到这个映射关系 - 它只扫描你指定路径下的 PHP 文件，提取其中带
@OA\Get这类注释的函数或类 - 所以必须把注释写在控制器方法上方，且该文件得被 PSR-4 或 require 能加载到
必须装对的两个 Composer 包
很多人卡在生成结果为空或报 Class "OpenApiAnnotations" not found，问题就出在这两包没配齐：
-
composer require zircote/swagger-php（v4.x，别装 v3 或 dev 分支） -
composer require openapi/openapi（v2.0+ 必须显式安装，v4 swagger-php 不再自带 annotation 类）
装完检查 vendor/zircote/swagger-php/src/Annotation.php 是否存在；如果 IDE 写 @OA\Get 不提示补全，八成是漏了 openapi/openapi。
立即学习“PHP免费学习笔记（深入）”；
注释必须紧贴方法，且命名空间不能省
Webman 控制器通常放在 app/controller 下，注释格式必须严格：
- 用完整命名空间：
@OA\Get，不是@Get或@SWGGet（v2 已废弃） - 注释块必须紧贴
function行上方，中间**不能空行** - 如果方法是
public function list(Request $request)，注释就得写在这一行正上方 - 确保控制器类本身有
namespace app\controller;，且文件路径与命名空间一致
错误示例：
/** @OA\Get(...) */<br><br>public function list(...)→ 扫描器跳过，不识别
生成 JSON 并接入 Swagger UI 的实操步骤
别指望 Webman 自带路由导出功能，老老实实用命令行生成 + 静态托管：
- 新建脚本
swagger.php在项目根目录：<?php<br>require 'vendor/autoload.php';<br>$openapi = \OpenApi\Generator::scan(['app/controller']);<br>file_put_contents('public/docs/openapi.json', $openapi->toJson()); - 执行
php swagger.php，确认public/docs/openapi.json有内容且含"openapi": "3.0.3" - 下载 Swagger UI dist，解压后把
dist/全部丢进public/docs/ - 修改
public/docs/index.html中的url: "./openapi.json" - 用 Web 服务器访问（如
php -S localhost:8000 -t public），别双击 HTML 文件——CORS 会拦截本地 JSON
最难的部分不在生成，而在于让 @OA\Response 真实匹配你 return json(...) 的结构。比如返回 ['data' => [...], 'code' => 0]，就得手写 @OA\JsonContent 描述 data 字段类型，否则前端看到的是 “unknown schema”。
