使用OpenAPI Generator生成Python客户端时遇ClassCastException

项目场景 #

正在为Allegro API开发Python客户端，使用7.0.0版本的openapi-generator-cli执行生成命令：

openapi-generator-cli generate -g python -i https://developer.allegro.pl/swagger.yaml -o /home/user/client

错误现象 #

执行命令时触发ClassCastException，生成器无法将UUID转换为字符串，错误日志如下：

Exception in thread "main" java.lang.RuntimeException: Could not process operation:
  Tag: class Tag {
    name: Advance Ship Notices
    description: null
    externalDocs: null
}
  Operation: deleteAdvanceShipNotice
  Resource: delete /fulfillment/advance-ship-notices/{id}
  Schemas: {BillingEntries=class ObjectSchema {
    class Schema {
(...)
}}
  Exception: class java.util.UUID cannot be cast to class java.lang.String (java.util.UUID and java.lang.String are in module java.base of loader 'bootstrap')
    at org.openapitools.codegen.DefaultGenerator.processOperation(DefaultGenerator.java:1225)
    at org.openapitools.codegen.DefaultGenerator.processPaths(DefaultGenerator.java:1120)
    at org.openapitools.codegen.DefaultGenerator.generateApis(DefaultGenerator.java:590)
    at org.openapitools.codegen.DefaultGenerator.generate(DefaultGenerator.java:953)
    at org.openapitools.codegen.cmd.Generate.execute(Generate.java:511)
    at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
    at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
Caused by: java.lang.ClassCastException: class java.util.UUID cannot be cast to class java.lang.String (java.util.UUID and java.lang.String are in module java.base of loader 'bootstrap')
    at org.openapitools.codegen.languages.AbstractPythonCodegen.toDefaultValue(AbstractPythonCodegen.java:185)
    at org.openapitools.codegen.DefaultCodegen.toDefaultValue(DefaultCodegen.java:2261)
    at org.openapitools.codegen.DefaultCodegen.fromProperty(DefaultCodegen.java:4129)
    at org.openapitools.codegen.DefaultCodegen.fromProperty(DefaultCodegen.java:3841)
    at org.openapitools.codegen.DefaultCodegen.fromParameter(DefaultCodegen.java:5116)
    at org.openapitools.codegen.DefaultCodegen.fromOperation(DefaultCodegen.java:4636)
    at org.openapitools.codegen.DefaultGenerator.processOperation(DefaultGenerator.java:1193)
    ... 6 more

相关OpenAPI接口定义 #

涉及的接口路径定义如下（报错的deleteAdvanceShipNotice结构与之类似）：

/fulfillment/advance-ship-notices/{id}/labels:
  get:
    summary: 'Get labels for Advance Ship Notice'
    description: 'Use this resource to get labels for Advance Ship Notice after being created with "create labels command".'
    tags:
      - Advance Ship Notices
    operationId: getAdvanceShipNoticeLabels
    parameters:
      - name: id
        in: path
        description: An identifier of the Advance Ship Notice.
        required: true
        schema:
          type: string
          format: uuid
        example: 84529ad2-2265-4e15-b76b-c17025d848f6
      - name: accept
        in: header
        description: Content-type of generated labels
        required: true
        schema:
          type: string
          enum:
            - application/pdf
            - x-application/zpl

成因分析 #

1. OpenAPI Generator解析规范时，会识别type: string且format: uuid的字段，将其内部解析为Java的UUID对象而非字符串。
2. Python代码生成器的AbstractPythonCodegen.toDefaultValue()方法处理该字段时，错误地将内部UUID对象强制转换为String类型，触发类型转换异常。
3. 尽管OpenAPI规范本身验证无问题，但openapi-generator-cli 7.0.0版本的Python代码生成器存在类型处理逻辑缺陷，未正确实现UUID到字符串的转换逻辑。

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