[admin-v2] Enable client generators to create proper class hierarchies with inheritance #46180

Pepo48 · 2026-02-10T13:24:31Z

mabartos · 2026-02-10T14:28:58Z

@michalvavrik @vmuzikar @robson90 Could you please check this PR? Thanks!

michalvavrik · 2026-02-10T14:40:49Z

Looking.

michalvavrik · 2026-02-10T14:58:03Z

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/oas/OASModelFilter.java

+     * Detects classes with @JsonAnyGetter and sets additionalProperties on their schemas.
+     * This reflects that the class accepts arbitrary additional JSON properties at runtime.
+     */
+    private void addAdditionalPropertiesToSchemas(OpenAPI openAPI) {


I am fine with doing this for any JsonAnyGetter provided they are missing from the generated OpenAPI document (which they are, I checked). But you explicitly speak about additonalProperties, so either:

you are dead certain there never will be any other such getter with different name

tweak javadoc or method name to clarify that this propagates any such a getter into openapi specs

filter method infos to only those with names getAdditionalFields

It is a nitpick...

We actually don't want anything to show up in the schema for JsonAnyGetter.

Ok, I didn't know. Also looking at the entry.getValue().setAdditionalPropertiesSchema(OASFactory.createSchema()); I think if it were to be present in the definition, you need to filter methods by name to do not include accidentally future getters.

The intention behind bringing back the additionalProperties was to try, whether it could solve issues with Kiota generator (reportedly it did). But I might've misunderstood the goal. Also I did not test this with Kiota myself - thus it is in a separate commit, which we can easily remove.

@michalvavrik can you confirm that this additionalProperties is what fixes the failures even for you and whether it is really what we need here?

Another approach would be adding the @Schema(additionalProperties = Schema.True.class), which I actually tried at first, but I decided not to use it, because it was syntactically different (generated just additionalProperties: true, not sure whether it poses some problem or not).

Thank you!

@michalvavrik can you confirm that this additionalProperties is what fixes the failures even for you and whether it is really what we need here?

it doesn't; gosh I need to make myself clearer in the future, sorry

So the issue with the kiota generator is that BaseRepresentation is empty in the generated OpenAPI document. But that is still the case, as currently, BaseRepresentation isn't augmented by the addAdditionalPropertiesToSchemas. Are there 2 ways I know about how to deal with it:

@edewit just removed @Schema and obviously unused BaseRepresentation disappeared, that is fine if we add comment that once the representation contains any properties, we would like to have it in the OpenAPI document

we can add dummy readonly property, e.g. A="1", but I looked into OpenAPI specs and I can't see how to instruct generators to never include it in clients. it is not nice, I'd not use it

Another approach would be adding the @Schema(additionalProperties = Schema.True.class), which I actually tried at first, but I decided not to use it, because it was syntactically different (generated just additionalProperties: true, not sure whether it poses some problem or not).

If there is no function for having the additionalProperties in the response, e.g. client doesn't need it, let's not do it.

Sorry for your time if you did it only because of my previous comments.

@michalvavrik no worries, it's misunderstanding on my end, partially caused by the fact that OpenAPI generator's behaviour was different. I just read your comment under Erik's PR and hopefully got the context. Now it should copy Erik's approach.

robson90 · 2026-02-11T15:59:42Z

For me the generation is failing, because of the non existent BaseRepresentation.

Logs:

[INFO] --- kiota:0.0.31:generate (default) @ keycloak-admin-openapi ---
[info] Going to execute the command: /Users/robinmeese/Documents/GitHub/meine/keycloak-client/admin-openapi/target/kiota/1.30.0/kiota generate --openapi /Users/robinmeese/Documents/GitHub/meine/keycloak-client/admin-openapi/src/main/resources/openapi-pr-46180.yaml --output /Users/robinmeese/Documents/GitHub/meine/keycloak-client/admin-openapi/target/generated-sources/kiota/org/keycloak/robin --language Java --class-name ApiClient --namespace-name org.keycloak.robin --type-access-modifier Public --serializer io.kiota.serialization.json.JsonSerializationWriterFactory --deserializer io.kiota.serialization.json.JsonParseNodeFactory --additional-data --log-level Warning
warn: Kiota.Builder.KiotaBuilder[534942631]
      OpenAPI warning: #/components/schemas/Auth/allOf/0/$ref - The schema reference '#/components/schemas/BaseRepresentation' does not point to an existing schema.
warn: Kiota.Builder.KiotaBuilder[534942631]
      OpenAPI warning: #/components/schemas/BaseClientRepresentation/allOf/0/$ref - The schema reference '#/components/schemas/BaseRepresentation' does not point to an existing schema.
warn: Kiota.Builder.KiotaBuilder[534942631]
      OpenAPI warning: #/ - Multiple servers entries were found in the OpenAPI description. Only the first one will be used. The root URL can be set manually with the request adapter.
crit: Kiota.Builder.KiotaBuilder[0]
      error generating the client: One or more errors occurred. (One or more errors occurred. (One or more errors occurred. (One or more errors occurred. (One or more errors occurred. (The type does not contain any information Path: \admin\api\{realmName}\clients\{version}, Reference Id: BaseRepresentation)))))

As said on Slack, my fix would be this part added to the openapi:

.....
    BaseRepresentation:
      type: object
      properties:
        additionalFields:
          type: object
          additionalProperties: { }
....

Just for testing I did change locally:

Outcome:

    BaseRepresentation:
      description: Base representation with common properties for all representation
        types
      type: object
      properties:
        additionalFields:
          type: object
          additionalProperties: {}

After compiling and pasting it in, Kiota is running without any complaints, the calls with an OIDCRep is working.
Depending on what the useCase for the BaseRepresentation is, this could be a feasible option.
When looking at the field, it seems like you want to achieve, that every Representation has a field of name additionalFields.

Now the part where I don't know, how fix. When calling get on a Client it has the type BaseClientRep. As the discriminator is in place, we can leverage instanceOf To know which type it is. For all properties that are in BaseClientRep should just work. For specific OIDC attributes, we need to cast it.

Only way right now, as an easy fix and also a nice usable api on the Java side could be to support all of this:

/clients -> will return Type BaseClientRepresentation
/clients/oidc -> will return Type OIDCClientRepresentation
/clients/saml -> will return Type SAMLClientRepresentation

Depending on the UseCase I would then use the respective function for updating resources.

WDYT?

For reference here are my testings: robson90/keycloak-client#3

michalvavrik · 2026-02-12T12:18:21Z

@Pepo48 the last time I read this PR it seemed fine and I didn't expect you to deal with BaseClientRepresentation. If you plan to, then additional work is probably needed. Please let us know once this is ready for a review so that you don't wait. Thanks.

Pepo48 · 2026-02-12T12:47:56Z

@michalvavrik OpenAPI generator didn't require any changes with regards to the base rep. Everything that is needed on top of my original PoC is just an attempt to help you guys, to stabilize Kiota.

That was the reason of the first attempt actually - I read the comment made by @robson90 from our offline conversation and tried to bring additionalFields back. But it didn't help to you, so I removed the schema completely to follow your suggestion, which broke it for Robin 😄.

But if I understand it correctly, then @JsonProperty("additionalFields") could work for both, right?

And as a next step I can try to add the return types that Robin suggested, if we agree on it.

Pepo48 · 2026-02-12T12:54:19Z

Regardless, feel free to bring your own adjustments at any point of time or anybody can take over this PR, if needed. My initial intention was just provide you with some basis that I already had, I don't have to necessarily drive this to the finish line (as I don't work with Kiota anyway, so you know better what you exactly need).

…s with inheritance Closes: keycloak#46158 Signed-off-by: Peter Zaoral <[email protected]>

michalvavrik · 2026-02-12T13:50:49Z

@michalvavrik OpenAPI generator didn't require any changes with regards to the base rep. Everything that is needed on top of my original PoC is just an attempt to help you guys, to stabilize Kiota.

Frankly, I had no idea that was the intention. I thought that you are fixing the class hierarchy, which seems helpful. Knowing this will help.

But if I understand it correctly, then @JsonProperty("additionalFields") could work for both, right?

IMO it would work if the additional properties were on BaseRepresentation and the BaseClientRepresentation extended it in the OpenAPI definition as well. (I am writing these names from the top of my head). but per Steven comment, I'd not go there.

Regardless, feel free to bring your own adjustments at any point of time or anybody can take over this PR, if needed. My initial intention was just provide you with some basis that I already had, I don't have to necessarily drive this to the finish line (as I don't work with Kiota anyway, so you know better what you exactly need).

Well, let see how much time I have tomorrow. I don't want your work to go waste, we can finish this one.

robson90 · 2026-02-12T15:06:04Z

That was the reason of the first attempt actually - I read the comment made by @robson90 from our offline conversation and tried to bring additionalFields back. But it didn't help to you, so I removed the schema completely to follow your suggestion, which broke it for Robin 😄.

Yeah, thanks for your investigation, this is now working "as expected".

Regrading my massive comments from above, we can also discuss the next steps on Monday.

PR itself LGTM, except CI is complaining about spotless...

IMO it would work if the additional properties were on BaseRepresentation and the BaseClientRepresentation extended it in the OpenAPI definition as well. (I am writing these names from the top of my head). but per Steven comment, I'd not go there.

@michalvavrik what is the exact use case for this attribute ?

michalvavrik · 2026-02-12T15:24:33Z

 @michalvavrik what is the exact use case for this attribute ?

I don't know yet. It is not relevant because I don't want to include it.

* add additionalFileds to base representation Closes: keycloak#46158 Signed-off-by: Peter Zaoral <[email protected]>

michalvavrik

Hello,

I had a look again and here is my conclusion.

ATM this PR resolves Kiota generation issue and LGTM
I lack knowledge about additionalFields, but IIUC @shawkins mentioned that we don't want them in the OpenApi document. In which case I can see only 2 options how to solve the "empty BaseRepresentation" issue:
- add discriminator to the BaseRepresentation as I assume we are going to need it eventually to determine if it is a client or realm, user, or ...?
- just bring back @JsonIgnore and drop @Schema as it has no function in regards to OpenAPI ATM

Thanks @Pepo48 for your work. You will have to decide what to do with your PR.

Pepo48 requested review from a team as code owners February 10, 2026 13:24

keycloak-github-bot bot added team/cloud-native labels Feb 10, 2026

mabartos requested review from michalvavrik and vmuzikar February 10, 2026 14:29

michalvavrik reviewed Feb 10, 2026

View reviewed changes

Pepo48 force-pushed the fix-v2-polymorphism branch from 322fd00 to dd30861 Compare February 10, 2026 19:19

[admin-v2] Enable client generators to create proper class hierarchie…

fa34050

…s with inheritance Closes: keycloak#46158 Signed-off-by: Peter Zaoral <[email protected]>

Pepo48 force-pushed the fix-v2-polymorphism branch from dd30861 to 7c6252d Compare February 12, 2026 12:58

Addressing reviews

b8acc5a

* add additionalFileds to base representation Closes: keycloak#46158 Signed-off-by: Peter Zaoral <[email protected]>

Pepo48 force-pushed the fix-v2-polymorphism branch from 7c6252d to b8acc5a Compare February 12, 2026 15:57

michalvavrik reviewed Feb 13, 2026

View reviewed changes

[admin-v2] Enable client generators to create proper class hierarchies with inheritance #46180

Are you sure you want to change the base?

[admin-v2] Enable client generators to create proper class hierarchies with inheritance #46180

Conversation

Pepo48 commented Feb 10, 2026

Uh oh!

mabartos commented Feb 10, 2026

Uh oh!

michalvavrik commented Feb 10, 2026

Uh oh!

michalvavrik Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

shawkins Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

michalvavrik Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Pepo48 Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

michalvavrik Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

michalvavrik Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Pepo48 Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

robson90 commented Feb 11, 2026

Uh oh!

michalvavrik commented Feb 12, 2026

Uh oh!

Pepo48 commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Pepo48 commented Feb 12, 2026

Uh oh!

michalvavrik commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robson90 commented Feb 12, 2026

Uh oh!

michalvavrik commented Feb 12, 2026

Uh oh!

michalvavrik left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Pepo48 commented Feb 12, 2026 •

edited

Loading

michalvavrik commented Feb 12, 2026 •

edited

Loading

michalvavrik left a comment •

edited

Loading