OpenAPI generator doesn't correctly handle data class schema references

[tandel-pratik]

Thanks for reporting an issue, please review the task list below before submitting the
issue. Your issue report will be closed if the issue is incomplete and the below tasks not completed.

NOTE: If you are unsure about something and the issue is more of a question a better place to ask questions is on Stack Overflow (https://stackoverflow.com/tags/micronaut) or Gitter (https://gitter.im/micronautfw/). DO NOT use the issue tracker to ask questions.

Task List

In Kotlin 1.3 and Micronaut 2.2.0 when a field had a type (lets say Address? in this case) was specified for a data class it would correctly compute generate the spec as:

class Foo(val address: Address)

components:
  schemas:
    Foo:
      address:
          $ref: '#/components/schemas/Address'

However with the upgrade to Kotlin 1.4 and the newest Micronaut upgrade (2.0.3 to 2.2.0), it doesn't generate the $ref correctly and generates it as an object type instead:

components:
  schemas:
    Foo:
      address:
          type: object

• Steps to reproduce provided
• Stacktrace (if present) provided
• Example that reproduces the problem uploaded to Github
• Full description of the issue provided (see below)

Steps to Reproduce

1. TODO
2. TODO
3. TODO

Expected Behaviour

Tell us what should happen

Actual Behaviour

Tell us what happens instead

Environment Information

• Operating System: TODO
• Micronaut Version: TODO
• JDK Version: TODO

Example Application

• TODO: link to github repository with example that reproduces the issue

[tandel-pratik]

I imagine it's this function ( https://github.com/micronaut-projects/micronaut-openapi/blob/master/openapi/src/main/java/io/micronaut/openapi/visitor/AbstractOpenApiEndpointVisitor.java#L380 ) that doesn't seem to have anything specific for nullable or Optional types? I also noticed that wrapping it in an Optional<Address> didn't do anything and semantically it should be the same as a nullable Address in the OpenAPI spec.

I put up an attempt at a fix here and would appreciate some feedback and best ways to write test for this: https://github.com/micronaut-projects/micronaut-openapi/pull/415/files

[tandel-pratik]

@alvarosanchez looking at this bug a bit more holistically i think the nullable types is a red-herring. The issue seems to be that it's no longer generating references correctly. See my original example and change the type of address from Address? to Address. This seems to be a regression after upgrading Micronaut

[alvarosanchez]

Could you please share an application that reproduces the issue so that we can investigate?

[tandel-pratik]

@alvarosanchez i tried to reproduce this in a standalone fashion but i couldn't (here's the attempt: https://github.com/pratik-brex/micronaut-demo/tree/ptandel/openapi_issue )

Our internal repository is using Bazel (instead of Gradle) and it's possible that that could potentially be a problem. We're using the same annotation processors defined here: https://github.com/micronaut-projects/micronaut-core/blob/2.2.x/inject-java/src/main/resources/META-INF/services/javax.annotation.processing.Processor

Were there any changes to how annotation processors were being handled or should i add new annotation processors? I noticed this PR might have included new annotation processors? #364 -- however it's interesting that most of the OpenAPI processors are working except for this example I showed below

Note: I noticed that downgrading Micronaut-OpenAPI to 2.1.3 didn't necessarily fix the issues.

Our schema is defined in a different target (effectively a different JAR) than the controllers / application, so i wonder if that's possible. The strange thing is that it's setting a $ref for an array but not the field, so for instance:

    @field:Schema(description = "Something else.")
    @field:Valid val address: Address?, // this doesnt
    @field:Schema(description = "some desc")
    @field:Valid val beneficial_owners: List<Address> // This works
)

[tandel-pratik]

So upon further digging, this seems to be the underlying issue: OpenAPI doesn't allow $ref with description (see OAI/OpenAPI-Specification#1514 for more details). It'd be ideal for the OpenAPI generator to print this as a warning :)

In the repro above, the micronaut generator is setting $ref and for some reason in my codebase it's setting description but not $ref