OpenAPITools / OpenAPITools/openapi-generator

[BUG][JAVA][PYTHON] Warnings displayed for discriminator property if "$ref" is used.

Open
#17,985 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

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?
  • What's the actual output vs expected output?
  • [Optional] Sponsorship to speed up the bug fix or feature request (example)
Description

When using OAPI3 "discriminator" support, openapi-generator generates warnings when discriminator properties are specified with "$ref".

This is not ideal for large APIs that wish to use a shared enum that contains the discriminator mappings for many objects.

It is possible to silence the warning by re-defining the discriminator's type property in each polymorphic API object. In the example spec posted, this would look like:

BarBazType:
    type: string
    description: A discriminator reference.
    enum:
      - BAR
      - BAZ
      
Baz:
  required:
    - type
  properties:
     type:
        type: string
        $ref: "#/components/schemas/BarBazType"

However, this produces an incorrect client, because the type property is generated as StrictStr with no enum constraints.

Actual output
... [main] WARN o.o.codegen.DefaultCodegen - 'Foo' defines discriminator 'type', but the referenced schema 'Bar' is incorrect. invalid type for type, set it to string [main] WARN o.o.codegen.DefaultCodegen - 'Foo' defines discriminator 'type', but the referenced schema 'Baz' is incorrect. invalid type for type, set it to string ...

Expected output
No warnings.

openapi-generator version

Bug detected on 7.2.0, confirmed against master (hash 6f01a7ad823).

OpenAPI declaration file content or url

Minimal spec to reproduce:
https://gist.github.com/Hnefi/86cb2d748748b468b449ed4984e71bef

Generation Details

Command-line parameters to reproduce:

openapi-generator generate -g python -i oapi3.yaml -o /tmp/python_client

Steps to reproduce
  1. Download the minimal API spec in the gist.
  2. Generate the client with the above command.
  3. Inspect warnings generated for the issue.
Related issues/PRs

The most relevant issue is:

Although the warning generated is the same, the root cause in my case seems to be the fact that the discriminator property in my minimal example uses "$ref".

Suggest a fix

When scanning the spec file to find the discriminator's property, inherit the type from child "$refs".

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 minimal OpenAPI spec in the linked gist and run the documented Python generation command to reproduce the DefaultCodegen warnings. Trace discriminator-property handling when the property uses $ref, including the related issue 17893. Done means generation produces no warnings and preserves the referenced enum constraints in the client.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.