OpenAPITools / OpenAPITools/openapi-generator
[BUG] model not generated when schema only referenced in parameters section
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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