Swagger JSON生成为空或报错，主因是扫描路径未覆盖控制器目录、注解语法不合规（如用@SWG而非@OA）、类未被Composer自动加载；需确保scan_dir精确指向含@OA注解的目录，使用OpenAPI 3.0规范写法，并在类顶部定义@OA\Schema。
Swagger JSON 文件生成命令执行后为空或报错
Hyperf 默认通过 php bin/hyperf.php swagger:generate 扫描注解生成 swagger.json，但常出现输出为空、提示“no valid annotations found”或直接抛出 ReflectionException。根本原因不是命令本身失效，而是扫描路径、注解语法、类加载三者没对齐。
- 确保
config/autoload/swagger.php中的scan_dir指向实际含@OA\注解的控制器/DTO 目录（例如app/Controller），不能只写app—— Hyperf 不递归扫描子目录 - 所有被扫描的 PHP 类必须能被 Composer 自动加载；若用了自定义命名空间（如
App\Api\V1\），需确认composer.json的autoload已包含该路径并执行过composer dump-autoload -
@OA\Get、@OA\Post等必须写在public方法上，且该方法所在类必须有@OA\Info或至少一个@OA\OpenApi全局注解（通常放在app/Controller下任意一个控制器顶部）
注解写法不兼容 OpenAPI 3.0 规范导致解析失败
Hyperf 2.2+ 使用 zircote/swagger-php 4.x，默认要求 OpenAPI 3.0 语法，但很多老项目沿用 2.x 风格的 @SWG\ 注解（如 @SWG\Parameter），这会导致扫描时静默跳过整个方法。
- 统一替换为
@OA\命名空间：例如@SWG\Get→@OA\Get，@SWG\Parameter→@OA\Parameter - 参数类型声明必须显式：
@OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"))，不能省略@OA\Schema或用type="int"（正确是type="integer"） - 响应体必须用
@OA\Response包裹@OA\JsonContent，且@OA\JsonContent的ref必须指向已定义的@OA\Schema，不能直接写ref="#/components/schemas/User"而不定义UserSchema
生成的 JSON 文件缺失接口或字段
即使命令成功执行，打开 storage/swagger/swagger.json 却发现只有 Info 信息、没有 Paths，或 DTO 字段没展开——这通常是注解位置或作用域问题。
-
@OA\Schema定义必须放在类文件顶部（非方法内），且类需有@OA\Schema标签和schema属性，例如：@OA\Schema(schema="User", title="用户")
，否则引用时无法解析 - DTO 类若含
__construct或属性未加public，swagger-php无法反射获取字段；确保属性声明为public $id;，而非protected $id; - 路由未绑定控制器方法（如用了
@Route但没配action），或控制器方法没加@RequestMapping/@GetMapping等路由注解，Swagger 扫描器会忽略该方法
开发环境能生成，线上环境失败
本地跑通，部署到 Docker 或生产服务器后 swagger:generate 报 Class not found 或直接无输出，大概率是生产模式下类加载优化或文件权限问题。
- 检查
APP_ENV是否为prod：Hyperf 在 prod 模式下默认关闭注解扫描缓存，需在config/autoload/annotations.php中显式开启scan_cacheable => true并确保缓存目录可写 - Docker 容器中执行命令前，先运行
composer install --no-dev --optimize-autoloader，否则部分注解类可能因 autoloader 未生成而不可见 - 确认
storage/目录在容器内有写权限（尤其 Alpine 镜像默认以非 root 用户运行），建议在 Dockerfile 中加RUN chmod -R 777 storage/
@OA\Parameter）都不会生效。最稳妥的做法是把全部 OpenAPI 描述收拢到独立的 Controller 或 Schema 文件里，远离条件分支和魔术方法。 
