webman集成swagger必须注释+扫描+托管三步闭环，否则openapi.json为空或404；因swagger-php仅扫描php源码中紧贴方法的@oa\注释，不解析route.php，且依赖psr-4自动加载。

Webman 集成 Swagger 不能靠“自动发现路由”，必须靠「注释 + 扫描 + 托管」三步闭环——漏掉任意一环，openapi.json 就是空文件或 404。

为什么 @OA\Get 注释写了却没生成接口？

Swagger-php 不解析 route.php，只扫描 PHP 源码中带 @OA\ 前缀的注释块。常见失效原因：

• 注释没紧贴方法：/** @OA\Get() */ 和 public function index() 中间有空行 → 被跳过
• 用了旧命名空间：@SWG\Get 或 @Get → v4 不识别，必须用 @OA\Get
• 控制器没声明命名空间，或路径与 namespace 不一致（如文件在 app/controller/User.php，但写的是 namespace app\ctrl;）
• vendor/openapi/openapi 没装：仅装 zircote/swagger-php 会报 Class "OpenApiAnnotations" not found

用 webman-tech/swagger 零配置启动的实操要点

这是目前 Webman 下最省事的方案，但默认行为容易踩坑：

Webman 2.2.0

Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。

下载

• 安装后访问 /openapi 404？检查是否启用了 global_route：它默认扫描 app_path()，但若你把控制器放在 app/api/ 下，需手动指定目录
• 文档里看不到请求体示例？确保在方法参数上加了 #[OA\RequestBody] 或 @OA\RequestBody，且引用了正确的 Schema 类
• 修改 title 或 version 失效？别只改 @OA\Info 注释——v5.1+ 推荐用配置项 modify 回调，它能动态覆盖生成结果
• 开发时改了注释但 UI 没更新？确认 app.php 中 'openapi_doc' => ['cache' => true] 在 dev 环境下设为 false，否则读缓存

手动生成 openapi.json 并托管到 /docs 的关键步骤

适合需要对接 YAPI、做 CI/CD 或禁用动态路由的场景，注意路径和权限：

• 脚本 swagger.php 必须用 __DIR__.'/app/controller'，不能写相对路径如 ../app/controller（Swoole 下工作路径不稳定）
• file_put_contents('public/docs/openapi.json', ...) 前确认 public/docs 目录存在且 Web 进程有写权限
• Swagger UI 的 index.html 里 url: "./openapi.json" 必须和实际 HTTP 路径一致；如果托管在 /api-docs，就得改成 url: "/api-docs/openapi.json"
• Nginx/Apache 需显式允许静态 JSON 访问：某些配置会拦截 .json 后缀走 PHP-FPM，导致下载而不是渲染

最常被忽略的是注释与类加载的关系：Swagger-php 只处理能被 require 或 PSR-4 自动加载的文件。如果你用 include 'xxx.php' 动态引入控制器，那些文件里的 @OA\ 注释永远不会被扫描到。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！