如何使openapi-generator生成的TypeScript客户端适配JavaSpring服务？

1. 确保OpenAPI YAML的鉴别器配置正确 #

先检查你的OpenAPI定义，确保discriminator的mapping字段正确关联了类型与对应字符串值，且父结构（承载oneOf逻辑的基类或属性容器）配置完整：

components:
  schemas:
    # 定义鉴别器的基类
    MetadataSchemaBase:
      type: object
      discriminator:
        propertyName: metadataSchema  # 鉴别器字段名
        mapping:
          raido-metadata-schema-v1: '#/components/schemas/PublicMetadataSchemaV1'
          raido-metadata-schema-v1-closed: '#/components/schemas/ClosedMetadataSchemaV1'
      required:
        - metadataSchema  # 强制要求携带鉴别器字段

    PublicMetadataSchemaV1:
      allOf:
        - $ref: '#/components/schemas/MetadataSchemaBase'
        - type: object
          properties:
            publicContent:
              type: string

    ClosedMetadataSchemaV1:
      allOf:
        - $ref: '#/components/schemas/MetadataSchemaBase'
        - type: object
          properties:
            closedContent:
              type: string

如果是直接在某个对象属性中使用oneOf（而非基于基类继承），也要确保鉴别器配置在该属性的父对象中，映射关系准确。

2. 调整Java Spring生成器参数，输出映射值而非类名 #

OpenAPI Generator的Java Spring生成器默认会用实体类名作为鉴别器值，需添加参数强制使用你定义的映射字符串：

在生成Java代码的命令中加入--additional-properties useDiscriminatorValue=true，完整命令示例：

openapi-generator generate \
  -i your-api-spec.yaml \
  -g spring \
  -o ./spring-server \
  --additional-properties useDiscriminatorValue=true,interfaceOnly=true

该参数会让生成的Java实体类中，@JsonSubTypes注解使用OpenAPI里定义的映射值，而非类名。生成的代码示例如下：

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "metadataSchema")
@JsonSubTypes({
  @JsonSubTypes.Type(value = PublicMetadataSchemaV1.class, name = "raido-metadata-schema-v1"),
  @JsonSubTypes.Type(value = ClosedMetadataSchemaV1.class, name = "raido-metadata-schema-v1-closed")
})
public class MetadataSchemaBase {
  // 类字段与方法
}

这样Spring序列化响应时，就会输出你定义的raido-metadata-schema-v1这类值，而非类名。

3. 确认TypeScript-fetch客户端生成配置 #

TypeScript-fetch生成器默认会正确解析OpenAPI中的鉴别器映射，生成对应的类型守卫与解析逻辑。如果之前生成的客户端有异常，可使用以下命令确保配置正确：

openapi-generator generate \
  -i your-api-spec.yaml \
  -g typescript-fetch \
  -o ./ts-client \
  --additional-properties supportsES6=true

生成的TypeScript代码会自动根据metadataSchema字段值判断具体类型，示例如下：

export type MetadataSchema = PublicMetadataSchemaV1 | ClosedMetadataSchemaV1;

export function MetadataSchemaFromJSON(json: any): MetadataSchema {
  return MetadataSchemaFromJSONTyped(json, false);
}

export function MetadataSchemaFromJSONTyped(json: any, ignoreDiscriminator: boolean): MetadataSchema {
  if ((json === undefined) || (json === null)) {
    return json;
  }
  switch (json['metadataSchema']) {
    case 'raido-metadata-schema-v1':
      return PublicMetadataSchemaV1FromJSONTyped(json, ignoreDiscriminator);
    case 'raido-metadata-schema-v1-closed':
      return ClosedMetadataSchemaV1FromJSONTyped(json, ignoreDiscriminator);
    default:
      throw new Error(`No match for discriminator value ${json['metadataSchema']} in MetadataSchema`);
  }
}

4. 验证结果 #

• 启动Spring服务，调用接口查看响应，确认metadataSchema字段值为你定义的映射字符串（如raido-metadata-schema-v1），而非类名。
• 使用TypeScript客户端调用接口，检查是否能正确解析为对应类型，无解析错误。

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