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

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: https://github.com/OAI/OpenAPI-Specification/issues/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

Start by reproducing the supplied OpenAPI 3.1 YAML with the spring generator, spring-boot library, and listed options, then compare the generated model names with the expected ListResponse and Item names. Investigate how external $ref schemas are resolved and named, and establish whether the finished work should change generation, add an option, or document the behavior.