OpenAPITools / OpenAPITools/openapi-generator

[BUG][4.3.1] The schema name is substituted with the path (under certain circumstances)

Open
#6,385 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Bug Report Checklist
  • Have you provided a full/minimal spec to reproduce the issue?
  • Have you validated the input using an OpenAPI validator (example)?
  • What's the version of OpenAPI Generator used? 4.3.1
  • Have you search for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Bounty to sponsor the fix (example)
Description

I switched from version 4.3.0 to 4.3.1 because I really need this fix #5830

With v4.3.1 the schema name is substituted with the path in the generated code.
The issue occurs under very particular circumstances but unfortunately it made all my API not working properly anymore. The circumstances are:

  • the main api (main.yaml) references a path located in another file (e.g., ./endpoints/orders_id.yaml) and containing a path param
  • for a response schema the path references a model located in an other file.

Please have a look to the example below to better understand the issue.

openapi-generator version

I am using v4.3.1.

It is not a problem of a specific generator. I am having the issue also with spring generator for instance.

I believe the issue is a regression.

OpenAPI declaration file content or url

./main.yaml
The main api file references a path located in ./endpoints/orders_id.yaml.

openapi: 3.0.2
info:
  title: order-api-spec
  version: 0.1.1

paths:
  "/orders/{id}":
    $ref: "./endpoints/orders_id.yaml#/paths/~1orders~1{id}"

./endpoints/orders_id.yaml
The GET /orders/{id} returns a model Order located in another file.

openapi: 3.0.2
info:
  title: orders-api-spec
  version: ignored

paths:
  "/orders/{id}":
    get:
      parameters:
        - in: path
          name: id
          description: Id of the target resource
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - order
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "../models/order.yaml#/components/schemas/Order"

./models/order.yaml

openapi: 3.0.2
info:
  title: orders-api-spec
  version: ignored

paths: {}

components:
  schemas:
    Order:
      type: object
      properties:
        name:
          type: string
Command line used for generation

$ java -jar openapi-generator-cli.jar generate -g openapi-yaml -i main.yaml -o ./out

Result with v4.3.0 (OK)
openapi: 3.0.2
info:
  title: cxp-api-spec
  version: ignored
servers:
- url: /
paths:
  /orders/{id}:
    get:
      parameters:
      - description: Id of the target resource
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
          description: Ok
      tags:
      - order
components:
  schemas:
    Order:
      example:
        name: name
      properties:
        name:
          type: string
      type: object
Result with v4.3.1 (KO)

Issues:

  • the model referenced in the response is actually the path: #/components/schemas/~1orders~1{id}
  • the Order schema is missing in #/components/schemas
openapi: 3.0.2
info:
  title: cxp-api-spec
  version: ignored
servers:
- url: /
paths:
  /orders/{id}:
    get:
      parameters:
      - description: Id of the target resource
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/~1orders~1{id}'
          description: Ok
      tags:
      - order
components:
  schemas: {}
Steps to reproduce
  • download and extract the attached zip -> example.zip
  • cd into it
  • run the cli generator with args generate -g openapi-yaml -i main.yaml -o ./out

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 by running the documented CLI command with main.yaml and the attached example, then compare the generated output with the v4.3.0 and v4.3.1 results. Inspect the references from endpoints/orders_id.yaml to models/order.yaml; done means the generated response points to Order and components/schemas contains the Order schema.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.