Enum schema names are nested and malformed

[swaechter]

Expected Behavior

The upgrade from Micronaut 3.7.7 to Micronaut 3.8.0 shouldn't break the OpenAPI

Actual Behavior

After upgrading from Micronaut 3.7.7 to Micronaut 3.8.0, more or less all enum schemas in our application/OpenAPI files are nested to another schema and thus malformed (Prefixed with Enum_ and with a trailing underscore). Example DTO with several enum/sub classes:

The generated OpenAPI references these subschemas as expected:

But following these enum schemas leads to a second, nested schema that is named differently to prevent schemas with the same name:

In addition, in the BackupSettingsDto, the value of the enum field now have an added object type (In 3.7.7 it was just a allOf + $ref)

Steps To Reproduce

That is the point that confuses me: I tried to reproduce the problem in https://github.com/swaechter/openapiproblems/tree/master/src/main/java/ch/swaechter/bug11 , but failed to do so. I am not sure what is the difference between my project and the bug example repo. I hope @altro3 can help out (There were several enum/JsonValue changes from reading the changelogs).

Environment Information

• Platform: Linux Debian
• Java: OpenJDK 64-Bit Server VM (build 17.0.4+8-Debian-1deb11u1, mixed mode, sharing)
• Micronaut Application Gradle Plugin: 3.7.2
• Micronaut Version: 3.8.0

Example Application

Not reproducible at the moment. https://github.com/swaechter/openapiproblems/tree/master/src/main/java/ch/swaechter/bug11 might serve as a starting point.

Version

3.8.0

[swaechter]

Not sure if #697 might be related.

[altro3]

@swaechter need to use latest version of micronaut-openapi. It's already fixed. Try use version 4.8.5. For your example openapi will be like this:

openapi: 3.0.1
paths:
  /:
    post:
      operationId: getBackupSettings11
      responses:
        "200":
          description: getBackupSettings11 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadBackupSettingsExDto'
components:
  schemas:
    BackupFrequencyExDto:
      type: object
      description: Schema that represents the frequency of the backup
      enum:
      - DAILY
      - MONDAY
      - TUESDAY
      - WEDNESDAY
      - THURSDAY
      - FRIDAY
      - SATURDAY
      - SUNDAY
    ReadBackupSettingsExDto:
      type: object
      properties:
        requiredBackupFrequency:
          allOf:
          - $ref: '#/components/schemas/BackupFrequencyExDto'
          - type: object
            description: Required backup frequency
        optionalBackupFrequency:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/BackupFrequencyExDto'
          - type: object
            description: Optional backup frequency. The key/value be omitted in the
              JSON result.
      description: Schema that represents the current backup settings

[altro3]

@swaechter Hmm.. But I noticed another bug: the enum type was determined incorrectly. Should be a string, but it was defined as an object. I fixed this issue here #969

[swaechter]

@altro3 Also thank you for this fix. It solved the enum nesting, but added a bug that inferfers with a lot of OpenAPI client generators. According to

• Reusable enums: https://swagger.io/docs/specification/data-models/enums/
• $ref and Sibling Elements https://swagger.io/docs/specification/using-ref/

a schema that uses $ref to reference another schema (E.g. backup that references an enum with the backup health) shouldn't specify the type. With the new releases. the following line shouldn't exists (Among others of course). For more information check out bug 12 https://github.com/swaechter/openapiproblems/blob/master/Swagger_3.8.8.yml#L188 .

Current, wrong code:

components:
  schemas:
    BackupDto12:
      type: object
      properties:
        location:
          allOf:
          - $ref: '#/components/schemas/BackupSubObject12'
          - type: object <---- Newly added, wrong
            description: Referenced class. $ref shouldn't specify the type of BackupSubObject12
        state:
          allOf:
          - $ref: '#/components/schemas/BackupSubEnum12'
          - type: object <---- Newly added, wrong
            description: Referenced enum. $ref shouldn't specify the type of BackupSubEnum12
      description: Schema to represent a backup

Code according to OpenAPI & code that doesn't break several OpenAPI client generators:

components:
  schemas:
    BackupDto12:
      type: object
      properties:
        location:
          allOf:
          - $ref: '#/components/schemas/BackupSubObject12'
          - description: Referenced class. $ref shouldn't specify the type of BackupSubObject12
        state:
          allOf:
          - $ref: '#/components/schemas/BackupSubEnum12'
          - description: Referenced enum. $ref shouldn't specify the type of BackupSubEnum12
      description: Schema to represent a backup

Btw: You are doing great work for the OpenAPi plugin. Is there a way to buy you coffee or do you have a whistlist (or something similar) :)

[altro3]

@swaechter Actually, this is not a bug. Yes, this is redundant information, but it is not a trifle. Maybe. I will remove this field later. If you don't specify an object type, then it is automatically assumed to be the default. You can check your swagger file at editor.swagger.io. Look at the screenshot

PS Not worth it :-). I'm just doing what I was missing when I was working on spring :-)

[swaechter]

@altro3 I see, you are right from a Swagger Editor point of view. Sadly, many OpenAPI client generators like typescript-axios or typescript-fetch pick up this type and generate invalid TypeScript code (Like an intersection which results in the type never - a type that is not/never usable from what I understand with my little frontend skills):

Generated BackupHealth enum:

Before Micronaut OpenAPI 4.8.6 (or deleting all type: objects in allOf of schemas):

After upgrading to Micronaut OpenAPI 4.8.6 (or not deleting all type: objects in allOf of schemas):

Of course one could argue that this is a bug in the client generator, but dropping the type: object in schemas would resolve it. At the moment I just delete all type: object as a workaround. So is there an advantage in mentioning the type?

PS: Ok, but let me know if I can buy you coffee or so. I really appreciate the effort you are putting into this module :)