OpenAPI: Automatically detected properties (and methods) are merged unwantedly

[timonzi]

Describe the bug

We switched from Quarkus 3.8.6 to 3.20.0 and got some problems with the OpenAPI schema definitions. For some types, we defined the schema via the Schema annotation to define, which properties should be used for REST requests. We did this in different variants, but none of them work with Quarkus 3.20.0. We always have properties (and also methods!?), which should not/never be part of the schema.

For example I have the following class:

@Schema(implementation = UseSchemaImplementationImpl.class)
public class UseSchemaImplementationType {

    private final String value;

    private final String internalValue = "internalValue";
    private final Boolean composite = true;

    public final boolean isNull() {
        return value == null;
    }
    // ... some other methods ...
}

The UseSchemaImplementationImpl looks like this:

public class UseSchemaImplementationImpl {

    private BigDecimal amount;
    private String currency;

    // ... constructor and getter/setter methods ....
}

In the OpenAPI schema I now have the following schema entries with Quarkus 3.20.0:

"UseSchemaImplementationImpl" : {
  "type" : "object",
  "properties" : {
    "amount" : {
      "type" : "number"
    },
    "currency" : {
      "type" : "string"
    }
  }
},
"UseSchemaImplementationType" : {
  "$ref" : "#/components/schemas/UseSchemaImplementationImpl",
  "type" : "object",
  "properties" : {
    "value" : {
      "type" : "string"
    },
    "internalValue" : {
      "type" : "string"
    },
    "composite" : {
      "type" : "boolean"
    },
    "null" : {
      "type" : "boolean"
    }
  }
},

In the Swagger UI I can see also the following "Example value":

{
  "value": "string",
  "internalValue": "string",
  "composite": true,
  "null": true
}

With Quarkus 3.15.4 it works as expected. There the schemas look like this:

"UseSchemaImplementationImpl" : {
  "type" : "object",
  "properties" : {
    "amount" : {
      "type" : "number"
    },
    "currency" : {
      "type" : "string"
    }
  }
},
"UseSchemaImplementationType" : {
  "$ref" : "#/components/schemas/UseSchemaImplementationImpl"
},

As a hint: We use own de-/serializer implementations for our types (not included in the reproducer). Here we use the amount and currency values to create the type. This of course does not work when the values internalValue, composite or null are provided.

Expected behavior

When I define an implementation class, only the properties from this class should be used. The ones from the actual/referencing class should not be merged/used. Additionally, I would not expect, that my getter methods (like isNull) is part of the schema. That doesn't really make sense to me. But maybe I'm missing something here where this could be useful.

Actual behavior

Properties of the UseSchemaImplementationType including getter methods (like isNull) are part of the schema, like shown above.

How to Reproduce?

Reproducer: https://github.com/timonzi/openapi-schema-reproducer

Steps to reproduce:

1. Start the application via mvn compile quarkus:dev
2. Access the swagger ui via http://localhost:8080/q/swagger-ui/#/

Alternative: Check the files in openapi/schema/

I also created a branch quarkus-3.15.4, which uses Quarkus 3.15.4. Here you can see the previous behavior.

Additionally I added a documentation about the problems in theREADME.md.

• Problem/scenario 1: Use of implementation property
• Problem/scenario 2: Use of ref property
• Problem/scenario 3: Use of native type as implementation (this requires not the usage of type = SchemaType.STRING with Quarkus 3.20.0)

Output of uname -a or ver

Linux nb-timonz 6.8.0-59-generic #61~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue Apr 15 17:03:15 UTC 2 x86_64 x86_64 x86_64 GNU/Linux

Output of java -version

OpenJDK 64-Bit Server VM Temurin-21.0.5+11 (build 21.0.5+11-LTS, mixed mode, sharing)

Quarkus version or git rev

3.20.0

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

Apache Maven 3.9.9

Additional information

No response

[quarkus-bot]

/cc @EricWittmann (openapi), @MikeEdgar (openapi), @phillip-kruger (openapi)

[MikeEdgar]

@timonzi thanks for the reproducer, I'll take a look at this.

[MikeEdgar]

@timonzi , until a fix is available, you can try setting mp.openapi.extensions.smallrye.openapi=3.0.4 in your configuration to use the OAS 3.0 format rather than the 3.1 format generated by more recent versions of the OpenAPI scanner. That should give you results closer to what you expect.

[timonzi]

@MikeEdgar Thank you for the hint. But, mp.openapi.extensions.smallrye.openapi=3.0.4 does not work for me. Here I get the following message in the swagger ui:

Unable to render this definition

The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.x.y (for example, openapi: 3.1.0).

I tried it also with mp.openapi.extensions.smallrye.openapi=3.0.3, which works in general. But the schemas are still wrong. For the UseSchemaImplementationType it only adds a allOf array with the ref to UseSchemaImplementationImpl. The other properties are still there.

"UseSchemaImplementationType" : {
  "type" : "object",
  "allOf" : [ {
    "$ref" : "#/components/schemas/UseSchemaImplementationImpl"
  } ],
  "properties" : {
    "value" : {
      "type" : "string"
    },
    "internalValue" : {
      "type" : "string"
    },
    "composite" : {
      "type" : "boolean"
    },
    "null" : {
      "type" : "boolean"
    }
  }
},

Now the example in the swagger ui looks like this (amount and currency were added):

{
  "amount": 0,
  "currency": "string",
  "value": "string",
  "internalValue": "string",
  "composite": true,
  "null": true
}

And of course the swagger ui displays also the wrong schema. I read this already as a workaround to use the allOf definition to hide the other fields, but that does not work for me.

[MikeEdgar]

FYI @timonzi , working on a fix in smallrye/smallrye-open-api#2266