OpenAPITools / OpenAPITools/openapi-generator

[BUG] model not generated when schema only referenced in parameters section

Open
#21,006 0 comments 1 reaction 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

When a schema is referenced only in the parameters section, that referenced model is not generated.

openapi-generator version

7.12.0

I am not sure it is a regression, I've not been following the releases closely.

OpenAPI declaration file content or url
---
openapi: 3.0.0
info:
  title: Pet
  version: v1

paths:
  /cats:
    parameters:
      - name: name
        in: query
        schema:
          type: string
      - name: age
        in: query
        schema:
          $ref: "#/components/schemas/age"
    get:
      description: get found cats
      responses:
        '200':
          description: cats
          content:
            application/json:
              schema:
                type: string

components:
  schemas:
    age:
      enum: [ BABY, YOUNGSTER, OLDY ]
Generation Details

Using the maven plugin to generate the code from the above definition

Steps to reproduce

When using the above yaml,

  • it leads to a warning:
[WARNING] #/components/schemas/age is not defined
  • the model file is written as an import in the pet.service.ts:
import { Age } from '../model/age';
  • but no model file for the enum age is generated

leading to compile time issues pointing to a referenced model that is not present.

The "workaround" is to adjust the definition slightly, ("type: string" to the "$ref: ..."):

    get:
      description: get found cats
      responses:
        '200':
          description: cats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/age"

Which has the effect that the age enum is referenced now also from beyond the parameters schema, and then:

  • no warning is shown
  • the import statement is still there
  • the model file for age is generated

Then it works. But not in all cases in my definition the schema is referenced from other places then the parameters - so this workaround is not feasible in all cases.

I've seen this happening for generators typescript-angular as well as the jaxrs-spec - I've not tried out others - so I suspect it is not related to the generators themselves.

Related issues/PRs

Both https://github.com/OpenAPITools/openapi-generator/issues/4710 and https://github.com/OpenAPITools/openapi-generator/issues/1123 point to a probable cause where definitions are split over files, but I could also imagine that both of these issues are there because there is only a reference from the parameters, and not from anywhere else.

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

Reproduce the supplied OpenAPI YAML with the Maven plugin, comparing typescript-angular and jaxrs-spec generation as described. Trace how a schema referenced only from path-level parameters is discovered; done means the warning is gone and the referenced age enum model is generated alongside its existing import.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.