[BUG] [Python] Ordering of schemas affect whether enum or BaseModel class generated when array is used with OpenAPI 3.1.0

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator (example)?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

When using an array type (supported in 3.1.0 specs and JSON schema), the generation of enum type generated in code is correct when it is defined before the reference but wrong (using BaseModel) when it is referenced after. I expect that the ordering does not matter here.

As a result of this, I am unable to parse the JSON returned by the server as the enum object in the client code.

Correct/Expected Output:

# client/model/kind.py
class Kind(str, Enum):
    """
    cat kind
    """

    """
    allowed enum values
    """
    SIAMESE = 'Siamese'
    TABBY = 'Tabby'

    @classmethod
    def from_json(cls, json_str: str) -> Self:
        """Create an instance of Kind from a JSON string"""
        return cls(json.loads(json_str))

Wrong/Actual Output:

# client/model/kind.py
class Kind(BaseModel):
    """
    cat kind
    """ # noqa: E501
    __properties: ClassVar[List[str]] = []

    model_config = {
        "populate_by_name": True,
        "validate_assignment": True,
        "protected_namespaces": (),
    }


    def to_str(self) -> str:
        """Returns the string representation of the model using alias"""
        return pprint.pformat(self.model_dump(by_alias=True))

openapi-generator version

latest/7.2.0

docker pull openapitools/openapi-generator-cli:latest
latest: Pulling from openapitools/openapi-generator-cli
Digest: sha256:7bfcb402ec4fef3af86c5ff38cec26c772db138120f931755da4a63a3cec5189

OpenAPI declaration file content or url

Note that Kind is before cat and this generates the correct output.

openapi: 3.1.0
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://petstore3.swagger.io/api/v3
paths:
  /pets:
    get:
      summary: Get pets
      operationId: getPets

      responses:
        '200':
          description: 'Get Pets'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cat'
components:
  schemas:
    Kind:
      type: string
      enum: [Siamese, Tabby]
      title: Kind
      description: cat kind
    Cat:
      type: object
      title: Cat
      description: a cat
      required: [kind]
      properties:
        kind:
          $ref: '#/components/schemas/Kind'
        y:
          prefixItems:
          - type: integer
          - type: integer
          - type: integer
          maxItems: 3
          minItems: 3
          title: Y
          type: array

This is with the Kind swapped around

openapi: 3.1.0
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://petstore3.swagger.io/api/v3
paths:
  /pets:
    get:
      summary: Get pets
      operationId: getPets

      responses:
        '200':
          description: 'Get Pets'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cat'
components:
  schemas:
    Cat:
      type: object
      title: Cat
      description: a cat
      required: [kind]
      properties:
        kind:
          $ref: '#/components/schemas/Kind'
        y:
          prefixItems:
          - type: integer
          - type: integer
          - type: integer
          maxItems: 3
          minItems: 3
          title: Y
          type: array
    Kind:
      type: string
      enum: [Siamese, Tabby]
      title: Kind
      description: cat kind

Generation Details

$ pip install openapi-spec-validator
$ openapi-spec-validator openapi.yaml
openapi.yaml: OK

$ docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli:latest generate -g python --additional-properties=generateSourceCodeOnly=true,packageName=client -o /local/ -i /local/openapi.yaml 

Note: I noticed the following NPE which could be the root cause. However, this happens for both cases, and in the correct ordering case, it produces Enum as expected. Hence, I expect this to be an orthogonal issue. It complains about the following:

...[main] ERROR o.o.codegen.DefaultGenerator - An exception occurred in OpenAPI Normalizer. Please report the issue via https://github.com/openapitools/openapi-generator/issues/new/:
java.lang.NullPointerException: Cannot invoke "io.swagger.v3.oas.models.media.Schema.get$ref()" because the return value of "io.swagger.v3.oas.models.media.Schema.getItems()" is null
	at org.openapitools.codegen.OpenAPINormalizer.processNormalize31Spec(OpenAPINormalizer.java:960)
	at org.openapitools.codegen.OpenAPINormalizer.normalizeSimpleSchema(OpenAPINormalizer.java:461)
	at org.openapitools.codegen.OpenAPINormalizer.normalizeSchema(OpenAPINormalizer.java:452)
	at org.openapitools.codegen.OpenAPINormalizer.normalizeProperties(OpenAPINormalizer.java:478)
	at org.openapitools.codegen.OpenAPINormalizer.normalizeSchema(OpenAPINormalizer.java:446)
	at org.openapitools.codegen.OpenAPINormalizer.normalizeComponentsSchemas(OpenAPINormalizer.java:375)
	at org.openapitools.codegen.OpenAPINormalizer.normalize(OpenAPINormalizer.java:196)
	at org.openapitools.codegen.DefaultGenerator.configureGeneratorProperties(DefaultGenerator.java:274)
	at org.openapitools.codegen.DefaultGenerator.generate(DefaultGenerator.java:1221)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:527)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

Steps to reproduce

1. Create openapi.yaml with Kind defined before Cat.
2. Notice generated code for kind.py is using a Enum sub class
3. Reorder Kind to be defined after Cat
4. Notice generated code for kind.py is now using BaseModel sub class

Related issues/PRs

When searching I found this which I thought might be relevant:

• https://github.com/OpenAPITools/openapi-generator/issues/16203 <-- when enum was generated as base model before.

Suggest a fix

I suspect the NPE could be an issue and somehow it continued but produced the wrong result.

Reproduce both OpenAPI 3.1.0 documents with the documented Docker command, then inspect OpenAPINormalizer.processNormalize31Spec at the reported stack-trace location. Compare the generated client/model/kind.py output for each schema order; done means both orders generate Kind as the Python Enum rather than BaseModel without the reported normalization failure.