OpenAPITools / OpenAPITools/openapi-generator

[BUG] `$ref` does not work under `paths/<uri>/<method>/parameters/<param>/schema`

Open
#7,897 2 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

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
  1. Use the sample yaml provided above as the OpenAPI specification file
  2. 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 php is only an example.*
  3. Observe [main] WARN o.o.codegen.utils.ModelUtils - #/components/schemas/Offer/properties/country is not defined emitted 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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.