[BUG][JAVA][SPRING] OpenAPI 3.1 external $ref schemas generate operation-based model names

[Ayushp7845]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• 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

After upgrading an API specification from OpenAPI 3.0.x to 3.1.0, model naming
changes when response schemas are defined in external files and referenced via $ref.

Instead of reusing the referenced schema name, openapi-generator generates
operation-based response models such as:

• GetItems200Response
• GetItems200ResponseDataInner

This occurs even when the referenced schema is explicitly named and reusable.

Related OpenAPI Specification discussion:
👉 <LINK TO MY OPENAPI-SPEC ISSUE>

openapi-generator version

7.16.0

OpenAPI declaration file content or url

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0

paths:
  /items:
    get:
      operationId: getItems
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/common.yaml#/components/schemas/ListResponse

External schema (schemas/common.yaml):

components:
  schemas:
    ListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        total:
          type: integer
      required:
        - data
        - total

    Item:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

Generation Details

Generator: spring
Library: spring-boot
Options:

• interfaceOnly=true
• useSpringBoot3=true
• generateAliasAsModel=true

Steps to reproduce

1. Define schemas in an external YAML file
2. Reference the schema in a response using $ref
3. Generate models using OpenAPI 3.1.0

Actual Output

GetItems200Response
GetItems200ResponseDataInner

Expected Output

ListResponse
Item

Related issues

OpenApi Specification issue: OAI/OpenAPI-Specification#5181

Suggest a fix

This may not be a bug but expected behavior per OpenAPI 3.1.

Possible improvements:

• Document this behavior clearly
• Provide a generator option to prefer referenced schema names when resolvable
• Clarify recommended structuring for external schema reuse in 3.1

[jackdevis]

@Ayushp7845 let me resolve this issue

[jackdevis]

I raised PR for this issue.

#22754

Please review my PR.
Regards