[BUG] "Unused model" warning for discriminator schemas from validate --recommend

[kevinoid]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator (example)?
• What's the version of OpenAPI Generator used?
• Have you search for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Bounty to sponsor the fix (example)

Description

Validating an OpenAPI 2 or 3 document which uses discriminator with --recommend will produce an "Unused model" warning for schemas which are only referenced by discriminator.

openapi-generator version

4.1.3

OpenAPI declaration file content or url

(Click to expand) OpenAPI 2 example (from the OpenAPI 2.0 spec with addition of `paths` for completeness).

swagger: '2.0'
info:
  title: Discriminator example from OpenAPI 2.0 specification
  version: '1.0.0'
definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
  Dog:
    description: A representation of a dog
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize
paths:
  /pets:
    get:
      operationId: getPets
      responses:
        '200':
          description: Success
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'

(Click to expand) OpenAPI 3 example (from the OpenAPI 3.0.2 spec with addition of `paths` for completeness).

openapi: '3.0.2'
info:
  title: OpenAPI 3.0.2 discriminator example
  version: '1.0.0'
servers:
- url: https://example.com/api
components:
  schemas:
    Pet:
      type: object
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
        properties:
          name:
            type: string
    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Dog`
        properties:
          bark:
            type: string
    Lizard:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Lizard`
        properties:
          lovesRocks:
            type: boolean

paths:
  /pets:
    get:
      operationId: getPets
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'

Command line used for generation

./openapi-generator-cli.jar validate --recommend -i openapi.yaml

Steps to reproduce

wget http://central.maven.org/maven2/org/openapitools/openapi-generator-cli/4.1.3/openapi-generator-cli-4.1.3.jar -O openapi-generator-cli.jar
chmod +x openapi-generator-cli.jar
vim openapi.yaml  # Paste example from above
./openapi-generator-cli.jar validate --recommend -i openapi.yaml

This should produce the following output:

Validating spec (openapi.yaml)
Warnings: 
	-Unused model: Cat
	-Unused model: Dog
	-Unused model: Lizard

[info] Spec has 3 recommendation(s).

Related issues/PRs

Possibly related: swagger-api/swagger-editor#765

Note: This issue also occurs with allOf, anyOf, oneOf without discriminator. Let me know if I should open a separate issue about those.

Thanks for considering,
Kevin

[jmini]

Thank you a lot for this bug report. I really appreciate the small spec you provided to display the issue.

I am not sure about the case you have proposed:
In your OpenAPI spec, you have one entry point (GET /pets) that is returning a Pet.
But you did not defined that Pet is either a Cat, a Dog or a Lizard. For me oneOf should be used in Pet (and then you probably will get trouble with the generated code, because at the moment not all generators supports oneOf well)

[kevinoid]

Thanks for the feedback @jmini. I chose this specific example because it was straight from the OpenAPI spec, so I assumed it would be uncontroversial. Can you imagine any use where discriminator (polymorphism) would be preferable to oneOf (discriminated union)? If so, it would trigger this issue.

[jmini]

Right… I just looked at the spec:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminatorObject

---

I am always combining discriminator with oneOf:

components:
  schemas:
    Pet:
      type: object
      oneOf:
      - $ref: '#/components/schemas/Cat'
      - $ref: '#/components/schemas/Dog'
      - $ref: '#/components/schemas/Lizard'
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'
          lizard: '#/components/schemas/Lizard'

---

But you are right there is also an implicit way of doing it, as you have provided in your example (the same as in the spec document)

[kevinoid]

Gotcha. I had misunderstood what you had in mind for oneOf. Thanks for explaining!

[jmini]

I have opened PR #4335 to support the case you have proposed in this issue when computing the list of Unused Schemas.