OpenAPI Generator如何忽略OpenAPI YAML中的缺失属性？

尝试基于HAPI FHIR的OpenAPI定义生成NestJS API客户端时，openapi-generator-cli报出大量参数缺失content字段的错误，示例如下：

[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/ExampleScenario'(get).parameters.[status].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/MedicinalProductPharmaceutical'(get).parameters.[_filter].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/Account/{id}/$diff'(get).parameters.[to].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/Organization/{id}/$validate'(get).parameters.[resource].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/VerificationResult'(get).parameters.[_id].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/StructureMap/{id}/$diff'(get).parameters.[to].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/AppointmentResponse'(get).parameters.[_id].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/EffectEvidenceSynthesis'(get).parameters.[_tag].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/ImmunizationRecommendation'(get).parameters.[_tag].content is missing
[[nestjs-generator] ./hapi-fhir-openapi.yaml]   -attribute paths.'/SearchParameter/{id}/$diff'(get).parameters.[from].content is missing

使用的openapitools.json配置如下：

{
  "$schema": "/home/myname/.nvm/versions/node/v14.15.0/lib/node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "6.0.1",
    "generators": {
      "nestjs-generator": {
        "generatorName": "typescript-nestjs",
        "output": "./output",
        "inputSpec": "./hapi-fhir-openapi.yaml",
        "additionalProperties": {
          "npmName": "hapi-fhir-api",
          "nestVersion": "8.0.0"
        }
      }
    }
  }
}

已尝试6.1.0、6.2.0版本及其他TypeScript生成器，错误依旧。Postman可正常导入该定义的所有API路径，但openapi-generator严格要求content字段必填，需解决如何忽略或跳过这些缺失字段的问题。

1. 跳过OpenAPI规范校验 #

openapi-generator默认会严格校验OpenAPI定义是否符合规范，可通过添加skipValidateSpec参数跳过校验，这是最直接的解决方法。

修改配置文件 #

在openapitools.json的生成器配置中添加skipValidateSpec: true：

{
  "$schema": "/home/myname/.nvm/versions/node/v14.15.0/lib/node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "6.0.1",
    "generators": {
      "nestjs-generator": {
        "generatorName": "typescript-nestjs",
        "output": "./output",
        "inputSpec": "./hapi-fhir-openapi.yaml",
        "skipValidateSpec": true, // 新增该行
        "additionalProperties": {
          "npmName": "hapi-fhir-api",
          "nestVersion": "8.0.0"
        }
      }
    }
  }
}

命令行方式运行 #

如果使用命令行直接调用生成器，添加--skip-validate-spec参数：

openapi-generator-cli generate -g typescript-nestjs -i ./hapi-fhir-openapi.yaml -o ./output --additional-properties npmName=hapi-fhir-api,nestVersion=8.0.0 --skip-validate-spec

2. 尝试更高版本的openapi-generator #

部分版本的openapi-generator对FHIR这类特殊OpenAPI定义的兼容性更好，建议尝试7.x及以上版本，可能已修复相关的校验逻辑。修改配置文件中的version字段：

"generator-cli": {
  "version": "7.6.0", // 替换为更高版本
  ...
}

3. 手动修正OpenAPI定义（可选） #

如果跳过校验后生成的代码存在问题，可手动修正OpenAPI定义中的参数部分：

• 对于查询参数（in: query），将缺失content的参数改为使用schema字段定义类型，例如：

  parameters:
    - name: status
      in: query
      required: false
      schema:
        type: string
  

• 但由于FHIR的OpenAPI定义体积庞大，手动修改成本较高，仅建议局部修正关键参数。

为什么Postman可以正常导入？ #

Postman对OpenAPI定义的兼容性校验更为宽松，允许存在部分不符合严格规范的字段；而openapi-generator默认遵循严格的OpenAPI规范校验逻辑，因此会抛出缺失content字段的错误。

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