[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

[Kavan72]

Let me clarify further since I am facing the same issue. Basically, the model is generated correctly when using OpenAPI version < 3.1. However, when upgrading to OpenAPI version ≥ 3.1, the generator starts adding Request, Response, and Inner as postfixes to the generated class names.

I am using the Spring Boot generator as well, similar to the person mentioned above. First, I want to understand whether this behavior is related to the OpenAPI standard itself. My assumption is that it has nothing to do with the OpenAPI specification and that there is some issue in the generator.

[Kavan72]

swagger-api/swagger-parser#2266

[urmichm]

I hope your contribution will be accepted, i had to downgrade :(

[dennisameling]

Given the upstream bug in swagger-parser mentioned above, I went ahead and submitted a potential fix upstream. I installed that version locally in my openapi-generator and ran it with:

java -jar ./modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -i issue-22753/main.yaml -g spring -o issue-22753/output-3-1-0 --library spring-boot -p interfaceOnly=true,generateAliasAsModel=true

Confirming that it generates Item and ListResponse as expected on the 3.1.0 spec that you provided:

So once upstream merges the fix and the swagger-parser version gets bumped here, the issue should be fixed.

[ulquio]

Hello,
Do we have any visibility on a fix for this bug?
I can confirm external $refs cause broken model naming, and I have plenty $ref in my project.
Downgrading to 3.0.0 is not an option because there is another major bug with relative paths inside $ref in this version: swagger-api/swagger-parser#2256 that requires modifying all relative paths.

Is there a workaround while waiting for this problem to be resolved?
The title field in the models doesn't seem to be working because then the generator duplicates the models ModelName1, ModelName2, etc.

Thanks