Enums are not correctly documented in Open API / Swagger UI in Quarkus 3.X

ilyakharlamov commented 11 months ago

Describe the bug

The issue is similar to https://github.com/quarkusio/quarkus/issues/25011 but for Quarkus 3.X When jackson-annotated enums are used for the openapi definition that is generated by quarkus-smallrye-openapi extension, then the jackson annotations like @JsonProperty are not respected. See the exact steps to reproduce below.

Expected behavior

I expect the enum values returned by the endpoint to match the OpenAPI definition generated by Quarkus SmallRye OpenAPI.

Actual behavior

In the JSON response, the enum values follow the Jackson @JsonProperty annotation and are serialized accordingly. However, the OpenAPI definition at /q/openapi does not reflect this. For enums, the actual JSON values and the OpenAPI definition schema do not match. This creates problems for clients using the endpoint.

How to Reproduce?

Steps to reproduce:

Get quarkus cli
Create a quarkus app with extensions for jackson and openapi: quarkus create app org.acme:getting-started --extension=quarkus-smallrye-openapi,quarkus-resteasy,quarkus-resteasy-jackson,quarkus-smallrye-openapi
Define a resource that uses enum:
```
package org.acme;
```

import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; import com.fasterxml.jackson.annotation.JsonProperty;

@Path("/hello") public class MyResource { public enum MyEnumSortOrder { @JsonProperty("mydesc") DESC, @JsonProperty("myasc") ASC }

public class MyClassWithEnum {
    private final MyEnumSortOrder myEnumSortOrder;
    public MyClassWithEnum(MyEnumSortOrder myEnumSortOrder){
        this.myEnumSortOrder = myEnumSortOrder;
    }
    public MyEnumSortOrder getMyEnumSortOrder() {
        return myEnumSortOrder;
    }
}

@GET
@Produces("application/json")
public MyClassWithEnum hello() {
    return new MyClassWithEnum(MyEnumSortOrder.DESC);
}

}

4. run quarkus `quarkus dev`
5. call the endpoint, this works OK: 
```sh
curl http://localhost:8080/hello
{"myEnumSortOrder":"mydesc"}

try to get the openapi definition:

# curl http://localhost:8080/q/openapi
---
openapi: 3.0.3
info:
title: getting-started API
version: 1.0.0-SNAPSHOT
paths:
/hello:
get:
  tags:
  - My Resource
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MyClassWithEnum'
components:
schemas:
MyClassWithEnum:
  type: object
  properties:
    myEnumSortOrder:
      $ref: '#/components/schemas/MyEnumSortOrder'
MyEnumSortOrder:
  enum:
  - DESC
  - ASC
  type: string
securitySchemes:
SecurityScheme:
  type: http
  description: Authentication
  scheme: basic

What's wrong:

The openapi definition for enums: DESC, ASC does not match the actual values that are generated by jackson: "mydesc", "myasc". So the clients that are generated from this openapi definition will not be compatible with this quarkus endpoint.

Expected behavior:

    MyEnumSortOrder:
      enum:
      - mydesc
      - myasc
      type: string

Output of `uname -a` or `ver`

Linux codespaces-4b5dcb 6.2.0-1012-azure

Output of `java -version`

openjdk version "17.0.8.1" 2023-08-24 LTS OpenJDK Runtime Environment Microsoft-8297089 (build 17.0.8.1+1-LTS) OpenJDK 64-Bit Server VM Microsoft-8297089 (build 17.0.8.1+1-LTS, mixed mode, sharing)

GraalVM version (if different from Java)

No response

Quarkus version or git rev

3.4.1

Build tool (ie. output of `mvnw --version` or `gradlew --version`)

Apache Maven 3.9.4

Additional information

No response

quarkus-bot[bot] commented 11 months ago

/cc @MikeEdgar (swagger-ui), @phillip-kruger (swagger-ui)

phillip-kruger commented 11 months ago

Please open this issue in the smallrye open api project

quarkusio / quarkus