OpenAPI代码生成失败：输入异常求助（升级工具仍无效）

问题场景 #

我在Node服务中使用OpenAPI Generator生成TypeScript-Axios代码，此前运行正常。但后端团队部署Swagger更新后，代码生成失败，报错如下：

Error: Command failed: 
    npx openapi-generator-cli generate     -g typescript-axios     -i  http://opt-my-service.edge2-ingress.capitol.is/v3/api-docs/MYORG    -o /Users/itaytur/Documents/GitHub/graphql-service/src/integrations/generated/opt-my-service     --skip-validate-spec     --type-mappings=set=Array     -p enumNameSuffix=,withoutPrefixEnums=false,supportsES6=true,apiPackage=apis,modelPackage=models,useSingleRequestParameter=true
    
Exception in thread "main" java.lang.RuntimeException: Issues with the OpenAPI input. Possible causes: invalid/missing spec, malformed JSON/YAML files, etc.

报错涉及的服务会变化，但错误信息一致。未部署更新的环境生成正常，已部署更新的环境则失败。我已升级@openapitools/openapi-generator-cli至2.16.2，并修改openapitools.json中的generator-cli版本为7.11.0：

{
  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "7.11.0"
  }
}

但问题仍未解决。

排查与解决方案 #

1. 直接校验Swagger规范合法性 #

尽管使用了--skip-validate-spec，新版本生成器可能对规范有更严格的隐性要求。先下载并校验spec文件：

• 用curl获取spec：

  curl http://opt-my-service.edge2-ingress.capitol.is/v3/api-docs/MYORG -o swagger-spec.json
  

• 检查文件是否存在语法错误（如JSON格式不完整）、不符合OpenAPI 3.x规范的字段（如废弃关键字、缺失type的schema）、无效的枚举或引用路径。

2. 移除--skip-validate-spec获取详细错误日志 #

--skip-validate-spec会屏蔽具体错误原因，移除该参数后重新运行生成命令，能得到精准的异常定位信息（比如哪个字段、路径的spec存在问题），这是排查后端更新问题的关键。

3. 确认后端Swagger更新内容 #

和后端团队同步更新点，重点排查：

• 是否新增了OpenAPI Generator不支持的扩展字段或复杂特性
• 是否修改了枚举类型、schema引用路径，导致生成器无法解析
• 是否存在空值、无效的字段定义（如缺失必填属性的schema）

4. 尝试降级OpenAPI Generator版本 #

新版本可能对规范兼容性有调整，尝试降级到之前能正常运行的generator-cli版本：

• 修改openapitools.json中的版本号为历史稳定版本（如7.8.0）
• 重新运行生成命令，验证是否恢复正常

5. 调整生成参数兼容性 #

检查参数是否与新版本生成器兼容：

• 确认withoutPrefixEnums、useSingleRequestParameter等参数在7.11.0版本中的有效性
• 先简化参数，仅保留-g、-i、-o基础参数，逐步添加其他参数，排查是否是特定参数引发的冲突

内容的提问来源于stack exchange，提问作者Itay Tur