OpenAPITools / OpenAPITools/openapi-generator
[BUG] `$ref` does not work under `paths/<uri>/<method>/parameters/<param>/schema`
Nobody has claimed this yet.
- 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)?
- Have you tested with the latest master to confirm the issue still exists?
- Have you searched for related issues/PRs?
Description
According to OpenAPI Specification v3.0.3 $ref is allowed to define the schema of a Parameter object, however when doing so code generation generates warnings such as WARN o.o.codegen.utils.ModelUtils - #/components/schemas/... is not defined, while the $ref pointer is definitely correct, for example it can be resolved fine by a variety of other tools.
openapi-generator version
This behaviour is the same for both v5.0.0-beta2 and v4.3.1. I've also checked against the latest snapshot.
OpenAPI declaration file content or url
Full example:
https://gist.github.com/BenceSzalai/908243fbe9a3107a11bf9093c77e31bc
Relevant excerpt:
paths:
/offer/:
get:
parameters:
- name: country
schema:
$ref: '#/components/schemas/Offer/properties/country'
components:
schemas:
Offer:
type: object
properties:
country:
type: string
Steps to reproduce
- Use the sample yaml provided above as the OpenAPI specification file
- run the local equivalent of
/bin/java -jar openapi-generator.jar generate -g php -i "sample.yaml" -o "generated"Actually the chosen generator doesn't matter,-g phpis only an example.* - Observe
[main] WARN o.o.codegen.utils.ModelUtils - #/components/schemas/Offer/properties/country is not definedemitted during generation.
*: In fact it exposes the issue more, since the $country parameter on DefaultApi::getOffer() in generated/lib/Api/DefaultApi.php gets type hinted with a non existent class: \OpenAPI\Client\Model\Country instead of string which should have been resolved from the $ref. But probably it has further consequences in other generators as well.
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
Start with the sample YAML and the local openapi-generator.jar generate -g php command to reproduce the warning from ModelUtils. Trace how the $ref under the parameter schema is resolved, then inspect the generated generated/lib/Api/DefaultApi.php; done means the reference resolves without a warning and the parameter is type hinted as string rather than a nonexistent Country model.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi, php
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100