[BUG] [kotlin-server] Does not create type mapping for oneOf (jaxrs-spec)

[rupert-jung-mw]

Description

It seems like the kotlin-server generator is not creating any type mappings as JSON annotations for Jackson when using oneOf + discriminator.

OpenAPI 3.1 (snippet)

# (within Model MyService)
      properties:
        serviceDetails:
          description: "Service specific details. Identified by the serviceType discriminator."
          oneOf:
            - $ref: '#/components/schemas/ServiceA'
            - $ref: '#/components/schemas/ServiceB'
          discriminator:
            propertyName: serviceType
            mapping:
              A: '#/components/schemas/ServiceA'
              B: '#/components/schemas/ServiceB'

Configuration (Maven) looks like this:

<configuration>
    <inputSpec>myfile.openapi.yaml</inputSpec>
    <generatorName>kotlin-server</generatorName>
    <skipValidateSpec>true</skipValidateSpec>
    <output>${project.build.directory}/generated-sources</output>
    <packageName>com.testing</packageName>
    <modelPackage>com.testing.myapi.dto</modelPackage>
    <apiPackage>com.testing.myapi.api</apiPackage>
    <generateApis>true</generateApis>
    <generateApiTests>false</generateApiTests>
    <generateModelTests>false</generateModelTests>
    <generateModelDocumentation>false</generateModelDocumentation>
    <generateSupportingFiles>false</generateSupportingFiles>
    <configOptions>
        <library>jaxrs-spec</library>
        <useJakartaEe>true</useJakartaEe>
        <useSwaggerAnnotations>false</useSwaggerAnnotations>
        <sourceFolder>src/main/java</sourceFolder>
        <dateLibrary>java8</dateLibrary>
        <serializationLibrary>jackson</serializationLibrary>
        <useBeanValidation>true</useBeanValidation>
        <openApiNullable>false</openApiNullable>
        <sortModelPropertiesByRequiredFlag>true</sortModelPropertiesByRequiredFlag>
        <sortParamsByRequiredFlag>true</sortParamsByRequiredFlag>
        <interfaceOnly>true</interfaceOnly>
    </configOptions>
</configuration>

Generated classes look like this:

data class ClassA(...): ServiceTOAllOfServiceDetails

data class ClassB(...): ServiceTOAllOfServiceDetails

interface MyClassAllOfServiceDetails

But there is no JSON type info generated.
I would expect something like

@JsonTypeInfo(use = NAME, include = PROPERTY, property = "serviceType")
@JsonSubTypes(
	JsonSubTypes.Type(value = ServiceA::class, name = "A"),
	JsonSubTypes.Type(value = ServiceB::class, name = "B"),
	
)
interface ServiceDetails 

So JSON in this form cannot be parsed:

{
    // ...
    "serviceDetails": {
        "serviceType": "A",
        // ...
    }
}

Error: Cannot construct instance of ServiceTOAllOfServiceDetails ... no Creators

openapi-generator version

7.24.0

OpenAPI declaration file content or url

(See above)

Generation Details

• Using kotlin-server generator with library `jax

Steps to reproduce

See above

Related merge requests

#22610

(I was under the impression, that this should actually work in 7.24.0)?

Thank you :)

[Mattias-Sehlstedt]

Please share more of your specification since there are several ways to express oneOf, and some of them the generator does not like. The entire schema carrying serviceDetails is necessary and it would also be good to include both the branches too.

Do you own the spec or is it someone else's? Generally models are only generated when they are concrete components and not inline definitions as serviceDetails is. There are settings for forcing and controlling inline schemas, but I do not know to what extent that they support being a oneOf.

[Mattias-Sehlstedt]

Within https://github.com/OpenAPITools/openapi-generator/pull/22610/changes we can also see that jaxrs-spec has not been modified, so the functionality added to data_class.mustache and associated will not affect jaxrs-spec since that library defines its own data_class.mustache which overrides the one defined in kotlin-server.

Edit: also raised by #22610 (comment).

[rupert-jung-mw]

Hi @Mattias-Sehlstedt , and thanks for your quick response.

Unfortunately I am not allowed to share the full specification as it is owned by one of our customers. :(
I did not know about these restrications for oneOf within an inline-definition. I was hoping, if would be enough that the type discriminator is given and present in all specified models as well as the mapping from discriminator value to model to use.

It worked with the java generator before so I assumed, the kotlin-server generator can also handle it. Maybe I'll change it back to java again as I am not in charge of the OpenAPI spec.

About the linked comment ("...only for the kotlin-server base generator?"): So that means, it works for ktor, javalin, but not for jax-rs, got it. I also tried it without specifiying a library (which should default to 'ktor' AFAIK) but even then, no type mapping annotations were added to the created classes.

[Mattias-Sehlstedt]

If it works in the Java generator then the structure of the oneOf should be valid.

The default library ktor should see some other code generation since it does not override data_class.mustache. But it is difficulty to say why it does not work as expected without a specification that can be used to reproduce anything.

Given the sample specifications used in the PR that introduced the logic I would at least assume that you would get a correct behavior if you were to manually adjust serviceDetails for an inline schema to a ref. So something similar to

MyService:
  properties:
    serviceDetails:
      description: "Service specific details. Identified by the serviceType discriminator."
      $ref: '#/components/schemas/ServiceDetails'
ServiceDetails:
  type: object
    required:
      - serviceType
    oneOf:
      - $ref: '#/components/schemas/ServiceA'
      - $ref: '#/components/schemas/ServiceB'
    discriminator:
      propertyName: serviceType
      mapping:
        A: '#/components/schemas/ServiceA'
        B: '#/components/schemas/ServiceB'

Could you at least obfuscate one of the children's structures? I would need to know that neither ServiceA nor ServiceB points to the parent with an allOf.

You could also run the generator with this structure and see that the polymorphism should work, and then compare that oneOf structure to yours.

[rupert-jung-mw]

Hello @Mattias-Sehlstedt,
thanks again.

I tried to extract ServiceDetails into it's own type using $refbut there is still no type mapping generated. The only difference is that it now doesn't create ServiceAllOfServiceDetails anymore but an empty interface ServiceDetails instead (where I would expect the type mappings to be generated into). For my untrained eyes, the specification looks exactly as in your example.

Next, I tried to use the linked pet-store API (polymorphism example) with this config:

  <execution>
    <id>OpenAPI Client generation - Petstore</id>
    <goals>
        <goal>generate</goal>
    </goals>
    <configuration>
        <inputSpec>
            ${project.basedir}/../api-management/src/main/resources/apis/petstore/petstore.openapi.yaml
        </inputSpec>
        <generatorName>kotlin-server</generatorName>
        <skipValidateSpec>true</skipValidateSpec>
        <output>${project.build.directory}/generated-sources</output>
        <packageName>com.something.petstore</packageName>
        <modelPackage>com.something.petstore.dto</modelPackage>
        <generateApis>false</generateApis>
        <generateApiTests>false</generateApiTests>
        <generateModelTests>false</generateModelTests>
        <generateModelDocumentation>false</generateModelDocumentation>
        <generateSupportingFiles>false</generateSupportingFiles>
        <configOptions>
            <library>jaxrs-spec</library>
            <useJakartaEe>true</useJakartaEe>
            <useSwaggerAnnotations>false</useSwaggerAnnotations>
            <sourceFolder>src/main/java</sourceFolder>
            <dateLibrary>java8</dateLibrary>
            <serializationLibrary>jackson</serializationLibrary>
            <useBeanValidation>true</useBeanValidation>
            <openApiNullable>false</openApiNullable>
            <sortModelPropertiesByRequiredFlag>true</sortModelPropertiesByRequiredFlag>
            <sortParamsByRequiredFlag>true</sortParamsByRequiredFlag>
            <interfaceOnly>true</interfaceOnly>
        </configOptions>
    </configuration>
</execution>

The result where these files:

petstore pm dtos.zip

As you see, even there Pet does not have any type mappings defined:

/**
 * Basic polymorphism example with discriminator No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
 *
 * The version of the OpenAPI document: 1.0
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). https://openapi-generator.tech Do not edit the class manually.
 */
package com.something.dto

import jakarta.validation.constraints.*

interface Pet

One of the concrete pets itself:

/**
 * Basic polymorphism example with discriminator No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
 *
 * The version of the OpenAPI document: 1.0
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). https://openapi-generator.tech Do not edit the class manually.
 */
package com.something.petstore.dto

import com.fasterxml.jackson.annotation.JsonProperty
import jakarta.validation.Valid
import jakarta.validation.constraints.*

/**
 * A pet dog
 *
 * @param petType
 * @param packSize the size of the pack the dog is from
 */
data class Dog(
    @JsonProperty("petType") @Valid @NotNull val petType: String,

    /* the size of the pack the dog is from */

    @JsonProperty("packSize") @Valid @NotNull @Min(0) val packSize: Int,
) : Pet

So it indeed just seems not work with kotlin-server + jaxrs-spec with 7.24.0. Looks like the template needs to be modified somehow.

[Mattias-Sehlstedt]

I was mainly interested in understanding why the default got such an odd result for you, but I saw now that ktor does not use jackson for serialization, and that that is the reason.

I was wondering whether adding something like

{{#discriminator}}
{{>typeInfoAnnotation}}
{{/discriminator}}

to the template could be a temporary fix, but when I generate the code Pet does not become an interface but rather a type alias. Given that it is caused by the {{#oneOf}} branch in the model.mustache file.

[rupert-jung-mw]

Hi @Mattias-Sehlstedt,

This seems to be a missunderstanding, I did never use ktor but jaxrs-spec with jackson (see snipped from pom.xml above).

<library>jaxrs-spec</library>
<serializationLibrary>jackson</serializationLibrary>

[Mattias-Sehlstedt]

TL;DR:
I wanted Pet to be used with ktor, it was used with jaxrs-spec. I tried it with ktor myself and found that it does not work.

Longer:
The misunderstanding is tied to how I wanted you to use the Pet specification example. Since comment two from me I knew that jaxrs-spec will never work. You had said

I also tried it without specifying a library (which should default to 'ktor' AFAIK) but even then, no type mapping annotations were added to the created classes.

I was surprised that this was the case, since I would expect the default to use the correct data_class.mustache and with that get polymorphism. So when I mentioned Pet in response to this comment I meant that we can try the default (ktor) with Pet, since we know Pet should produce polymorphism, since that is what the PR author used.

What was instead done was that we used Pet for jaxrs-spec, which will not produce anything interesting since we are still stuck with the incorrect mustache file. I then Instead tried it myself locally, but found that there was no Jackson annotations as expected, I investigated and then found that ktor does not even use Jackson, and thus that the test that I had suggested will not produce any interesting information.
Hence

I was mainly interested in understanding why the default got such an odd result for you, but I saw now that ktor does not use jackson for serialization, and that that is the reason.

As a comment from me.

---

The way forward for jaxrs-spec would be to make sure it gets the mappings in its mustache files. Nut ensuring it is the same as the others is a slightly large task. One hail mary one could do is to try this suggestion

I was wondering whether adding something like

{{#discriminator}}
{{>typeInfoAnnotation}}
{{/discriminator}}

to the template could be a temporary fix, but when I generate the code Pet does not become an interface but rather a type alias. Given that it is caused by the {{#oneOf}} branch in the model.mustache file.

[rupert-jung-mw]

Hello @Mattias-Sehlstedt , ah, I see, thanks for clarification makes sense then. Yes we tried to override the template with something like this:

oneof_model.mustache:

{{#-first}}
{{#discriminator}}
{{>typeInfoAnnotation}}
interface {{classname}}
{{/discriminator}}
{{^discriminator}}
typealias {{classname}} = Any
{{/discriminator}}
{{/-first}}

via

 <templateDirectory>${project.basedir}/src/main/resources/openapi-templates/kotlin-server-jaxrs-spec</templateDirectory>

This creates an in-between interface like this:

@com.fasterxml.jackson.annotation.JsonTypeInfo(
    use = com.fasterxml.jackson.annotation.JsonTypeInfo.Id.NAME,
    include = com.fasterxml.jackson.annotation.JsonTypeInfo.As.PROPERTY,
    property = "serviceType",
    visible = true,
)
@com.fasterxml.jackson.annotation.JsonSubTypes(
    com.fasterxml.jackson.annotation.JsonSubTypes.Type(value = ServiceA::class, name = "A"),
    com.fasterxml.jackson.annotation.JsonSubTypes.Type(value = ServiceB::class, name = "B"),
)
interface ServiceTOAllOfServiceDetails

But I was hoping for an 'official' fix / polymorpism support for kotlin-server as I am not sure, if this is enough...