openapitools/openapi-generator-cli 无法通过 Composer 正常安装，因其是 Java CLI 工具而非 PHP 包；生成的 PHP 客户端默认不兼容 Laravel/原生项目，需指定模板或调整参数；oneOf 导致模型退化为 stdClass；异步方法返回 Promise 需手动 wait 或禁用。
composer require openapitools/openapi-generator-cli 为什么装不上
根本原因不是命令写错了，而是 openapitools/openapi-generator-cli 是一个基于 Java 的 CLI 工具，它本身不提供 PHP 类库，也不支持直接通过 Composer 加载为依赖运行。Composer 只管 PHP 包，而这个包只是个“下载器+脚本包装器”，实际执行靠本地 Java 环境。
常见错误现象：Could not find package openapitools/openapi-generator-cli（旧版 Packagist 没收录），或装上了却调用 openapi-generator 命令时报 command not found 或 Java not found。
- 必须提前装好 Java 11+（
java -version要能输出 11 或更高） - 推荐用官方方式安装 CLI：下载 JAR 包 + 写 shell 别名，而不是强求 Composer 管理
- 如果非要用 Composer，可改用
bbtsoftware/php-openapi-generator这类纯 PHP 实现（但功能和维护活跃度弱很多）
openapi-generator generate -g php 生成的代码为啥不能直接 new Client()
默认生成的 PHP 客户端（-g php）是为 Zend Framework / Laminas 设计的结构，依赖 laminas-http、laminas-json 等组件，并且入口类名、命名空间、构造函数参数都和 Laravel 或原生 PHP 项目不兼容。
典型问题：Class 'OpenAPIClientApiDefaultApi' not found，或者 Client::__construct() expects at least 2 parameters。
立即学习“PHP免费学习笔记（深入）”；
- 加
--additional-properties=phpNamespace=MyApp\Api,srcBasePath=src显式控制命名空间和路径 - 用
-g php-symfony或-g php-laravel替代默认php，它们会生成更现代的 PSR-4 结构 - 生成后务必运行
composer dump-autoload，否则自动加载找不到新类 - 别忽略
config.php或Configuration.php—— 它控制 base path、auth、timeout，漏配就 401 或超时
openapi.yaml 里用了 oneOf / anyOf，生成的 PHP 模型为啥全是 stdClass
PHP 本身没有联合类型运行时支持，openapi-generator 遇到 oneOf 默认退化为 object（即 stdClass），不生成具体子类，也不带类型提示，导致 IDE 无法补全、运行时易出错。
这不是 bug，是设计取舍：保证生成稳定 vs 提供精确类型。想让模型可读可用，得干预生成逻辑。
- 加
--additional-properties=useOneOfDiscriminator=true启用鉴别器字段识别（需 OpenAPI 文档中定义discriminator.propertyName） - 手动在 YAML 中给
oneOf成员加x-php-class扩展字段，例如：x-php-class: "MyApp\Model\PaymentCard" - 更稳妥的做法是避免在关键接口中用
oneOf，改用明确的 endpoint 分离（如/pay/card和/pay/paypal）
生成的 API 类方法返回 Promise？PHP 里哪来的 Promise
这是 -g php 模板历史遗留问题：它默认启用异步支持（基于 guzzlehttp/promises），所有方法都返回 Promise 对象，但 PHP 没有原生 async/await，你得手动 $promise->wait()，否则拿不到结果。
结果就是写了 $api->getUser()->then(...) 却卡住不动，或者抛出 Call to a member function then() on array —— 因为有些响应被直接 decode 成了数组。
- 加
--additional-properties=async=false关掉 Promise，方法直接返回array或模型实例 - 若真需要异步，用
-g php-symfony+HttpClient，它返回 Symfony 的Response，配合then()更可控 - 注意：关掉 async 后，错误仍通过异常抛出（
ApiException），不是返回 false 或 null
真正麻烦的是文档没写清楚哪些字段是 required、哪些是 nullable，生成器又不会帮你做运行时校验 —— 模型类里属性全设成 public，赋值全靠自觉。这点比手写还容易漏。
