swagger-api / swagger-api/swagger-parser

[Question]: Duplicate _1 Object generation due to different path prefix

Open
#2,253 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Question
Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

Question

I'm trying to parse 2 API Specifications in OpenAPI 3.0.3 using OpenApiGenerator version 7.1.0. One has the TO (lets call it BrokenTO) directly as response object, the other one has a TO (lets call it ObjectThatContainsBrokenTO) that includes the TO from the first API. This results in ObjectThatContainsBrokenTO having a reference to BrokenTO_1 not BrokenTO. The other API Spec parses correctly with BrokenTO reference.
I already verified the paths to the object in question are the same. I also tried putting both TO yaml descriptions into the same folder so the path is exactly the same

Affected Version

2.1.36 from the OpenAPI Generator

Context

openapi: 3.0.3
info:
  title: Our API
  version: 1.0.0
tags:
  - name: SomeTag

paths:
  /classified/path/:
    $ref: "ClassifiedAPI.yaml"
  /another/classified/path:
    $ref: "Classified2APIyaml"

#ClassifiedAPI.yaml
post:
  operationId: anotherOperationId
  parameters:
  requestBody:
    content:
      application/json:
        schema:
          $ref: 'ObjectThatContainsTheBrokenTO.yaml'
 

#ObjectThatContainsTheBrokenTO.yaml
type: "object"
properties:
  aparameter:
    $ref: "aTO.yaml"
  anotherparameter:
    $ref: "anotherTO.yaml"
  parameterinquestion:
    type: "array"
    items:
      $ref: "../folder/folder2/BrokenTO.yaml"

#Classified2APIyaml
get:
  operationId: someoperation
  parameters:
  # some parameters
  responses:
    '200':
      description: Ok!
      content:
        application/json:
          schema:
              $ref: "../folder/folder2/BrokenTO.yaml"

Additional Details

These yaml definitions are generated as the BrokenTO.java class but also as a reference to BrokenTO_1 is generated into the Java files for ObjectThatContainsTheBrokenTO.java.

While debugging the generator code I found a difference in how the $refs are created and later stored in the cache. One time it has a leading ./ but the other time it has not.

Image

Question: Why is the path prefixed with ./ in one case but not the other?
Follow up: Couldn't all paths be prefixed with ./ since it does not make a difference? To be extra sure the file is the same a hash could be used to verify the content is identical. Would you agree with that? Is that something for a PR?

I found the following discussions/issues but nothing that matched my use case and/or resolved it:

https://github.com/swagger-api/swagger-parser/issues/1081#issuecomment-607169681
https://github.com/OpenAPITools/openapi-generator/issues/2701
https://github.com/OpenAPITools/openapi-generator/issues/20454

Thanks :)

Checklist

  • I have searched the existing issues and documentation before asking.
  • I have provided enough information for others to understand my question.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with ObjectThatContainsBrokenTO.yaml, Classified2APIyaml, and the ../folder/folder2/BrokenTO.yaml references; compare the two $ref strings at the cache boundary described in the issue. Use the supplied OpenAPI 3.0.3 reproducer to verify whether path normalization prevents BrokenTO_1 while preserving both generated BrokenTO.java references.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.