[kotlin-spring][server] Feat: Allow implementation of arbitrary interface in DTOs (similar to x-implements from java-spring) #21950

Picazsoo · 2025-09-11T09:11:35Z

This PR adds support for two new vendor extensions named x-kotlin-implements and x-kotlin-implements-fields.

x-kotlin-implements - a list of fully qualified interface(s) that should be implemented by a DTO
x-kotlin-implements-fields - a list of fields that are backed by the interface(s). This is necessary because unlike java, one has to add a keyword override in front of the fields originating from the interfaces. The open api generator has no way of knowing which fields exist in the interfaces, so the fields names have to be provided via this vendor extension for the code to compile correctly. If x-kotlin-implements is missing on the schema definition, this extension is ignored entirely.

I implemented some basic tests - verified that my changes do not break the current way of handling inheritance and Serializable implementation. Also the java logic related to the implementation is in such a place that it should allow for a pretty easy implementation of the feature in the other kotlin code generators. I want to gather feedback whether this approach is acceptable. I decided against reusing x-implements as I can imagine the same swagger document being used in environments with mixed tech-stack, so I though that being able to implement different interfaces for java and kotlin might be useful. But I am ok with changing the extensions to x-implements and x-implements-fields if it increases the chance of having this merged into the codebase.

I could not find an issue ticket for exactly this issue, so I went ahead and created the PR without linking anything. I hope it is ok.

PR checklist

Read the contribution guidelines.
Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
Run the following to build the project and update samples:
```
./mvnw clean package || exit
./bin/generate-samples.sh ./bin/configs/*.yaml || exit
./bin/utils/export_docs_generators.sh || exit
```
(For Windows users, please run the script in WSL)
Commit all changed files.
This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
These must match the expectations made by your contribution.
You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
If your PR solves a reported issue, reference it using GitHub's linking syntax (e.g., having "fixes #123" present in the PR description)
If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request. - tagging: @dr4ke616 , @karismann , @Zomzog , @andrewemery , @4brunu , @yutaka0m , @stefankoppier , @e5l

Picazsoo · 2025-09-11T09:15:43Z

modules/openapi-generator/src/main/resources/kotlin-spring/dataClass.mustache

+){{/discriminator}}{{! no newline
+}}{{#parent}} : {{{.}}}{{! no newline


This misuse of comments to prevent line break might be controversial. However it seemed to improve the readability as otherwise the line would be very very long. But I can do one-liner if it is preferred to this.

Picazsoo · 2025-09-11T09:16:24Z

modules/openapi-generator/src/test/resources/3_0/kotlin/petstore-with-x-kotlin-implements.yaml

+      x-kotlin-implements: [ 'com.some.package.Named' ]
+      x-kotlin-implements-fields: [ name ]


this is the way the vendor extension is used - define the interface and then specify the actual fields that should have the override keyword prepended.

thanks for adding a test spec (used in java unit tests)

can we also include a samples generated from this spec by adding a yaml config file under ./bin/config and add the new folder to the github workflow (.github/workflows/samples-kotlin-client.yaml) to ensure the output compiles without issues?

Cool. I am on it. That definitely makes sense and I was wondering how the ability to compile is checked.

Hi, I hope I did it correctly. It was definitely worthwhile as I uncovered a mistake in one of my template changes. I added the generated files (and manually added the interfaces the models must implement) and added the output folder to the samples-kotlin-client.yaml. Hope that is all that is needed for now - I guess the pipelines should now automatically pick it up for compilation?

Picazsoo · 2025-09-11T09:19:49Z

modules/openapi-generator/src/main/resources/kotlin-spring/enumClass.mustache

 * Values: {{#allowableValues}}{{#enumVars}}{{&name}}{{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}}
 */
-enum class {{classname}}(@get:JsonValue val value: {{dataType}}) {
+enum class {{classname}}(@get:JsonValue val value: {{dataType}}) {{#vendorExtensions.x-kotlin-implements}}{{#-first}}: {{{.}}}{{/-first}}{{^-first}}, {{{.}}}{{/-first}}{{/vendorExtensions.x-kotlin-implements}}{


I think implementing the interface on enum is a bit useless as the only thing one can implement on generated enum is an interface with some default methods? Or correct me if I am wrong.

I did it here mostly to achieve parity with java x-implements.

Picazsoo · 2025-09-11T09:20:27Z

samples/server/petstore/kotlin-spring-cloud/src/main/kotlin/org/openapitools/model/Category.kt

    @get:Pattern(regexp="^[a-zA-Z0-9]+[a-zA-Z0-9\\.\\-_]*[a-zA-Z0-9]+$")
    @get:JsonProperty("name") val name: kotlin.String? = null
-    ) : Serializable{
+) : Serializable {


just formatting changes - there are lot of those.

wing328 · 2025-09-12T07:53:30Z

Thanks for the PR but your commit (as shown in the Commits tab) is not linked to your Github account, which means this PR won't count as your contribution in https://github.com/OpenAPITools/openapi-generator/graphs/contributors.

Let me know if you need help fixing it.

Ref: https://github.com/OpenAPITools/openapi-generator/wiki/FAQ#how-can-i-update-commits-that-are-not-linked-to-my-github-account

Picazsoo · 2025-09-12T09:41:26Z

...penapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractKotlinCodegen.java

+        List<String> implementedInterfacesClasses = (List<String>) m.getVendorExtensions().getOrDefault(VendorExtension.X_KOTLIN_IMPLEMENTS.getName(), List.of());
+        List<String> implementedInterfacesFields = implementedInterfacesClasses.isEmpty()
+                ? List.of()
+                : (List<String>) m.getVendorExtensions().getOrDefault(VendorExtension.X_KOTLIN_IMPLEMENTS_FIELDS.getName(), List.of());


Would it make sense to log some info or warn here if the x-kotlin-implements-field is defined on the model without corresponding x-kotlin-implements? To make it a bit more user-friendly?

sounds good to me. please add some log

…sion map

… extends interface.

…n-implements to improve usability

Picazsoo · 2025-09-15T08:57:47Z

I added the warn logs as well as more complex case of the arbitrary interface being extended by a schema with discriminator - hence generated interface extending the custom interface. Is anything more needed?

I also tried to fix the issue with the email in commits - hope I did it correctly.

… Pet.Status in implementations. This is a separate bug - not caused by x-kotlin-implements

Picazsoo · 2025-09-15T15:31:24Z

I removed the "status" enum from Pet definition as it fails to generate code that will compile. This is not caused by my changes - it is some already existing bug related to how inner enums are handled in inheritance.

wing328 · 2025-09-15T17:54:56Z

I removed the "status" enum from Pet definition as it fails to generate code that will compile.

👌

agreed we can look into that later with a separate pr to fix it

…face in DTOs (similar to x-implements from java-spring) (OpenAPITools#21950) * add basic implementation and tests * improve test a bit * modify kotlin-spring.md * add x-kotlin-implements also to enum * update samples & properly define implemented vendor extension * use enum.getName() instead of hardcoded string as key in vendor extension map * fix docs * fix test openapi spec and test * add samples for x-kotlin-implements * add samples for x-kotlin-implements to proper output folder * fix * revert unwanted changes * move to correct place * fix mustache template * add to samples-kotlin-server.yaml * reuse 1 open api schema for everything. Add also case where interface extends interface. * add warn logs when x-kotlin-implements-fields is used without x-kotlin-implements to improve usability * remove unnecessary generated files * remove unnecessary generated files * remove "status" inner enum from Pet as it fails to properly import as Pet.Status in implementations. This is a separate bug - not caused by x-kotlin-implements

Picazsoo changed the title ~~Feat/implement x implements for kotlin spring~~ [kotlin-spring][server] Feat: Allow implementation of arbitrary interface in DTOs (similar to x-implements from java-spring) Sep 11, 2025

Picazsoo commented Sep 11, 2025

View reviewed changes

Picazsoo commented Sep 12, 2025

View reviewed changes

Picazsoo force-pushed the feat/implement-x-implements-for-kotlin-spring branch from f61c542 to 7198cdd Compare September 15, 2025 08:03

Picazsoo added 17 commits September 15, 2025 10:35

add basic implementation and tests

184b96b

improve test a bit

acda457

modify kotlin-spring.md

1f89def

add x-kotlin-implements also to enum

eb4da41

update samples & properly define implemented vendor extension

2cfd787

use enum.getName() instead of hardcoded string as key in vendor exten…

1298b21

…sion map

fix docs

709919e

fix test openapi spec and test

bb54fc9

add samples for x-kotlin-implements

b2d9135

add samples for x-kotlin-implements to proper output folder

6894f07

fix

b0c57c8

revert unwanted changes

325fbdd

move to correct place

6013278

fix mustache template

7c665eb

add to samples-kotlin-server.yaml

b1141e1

reuse 1 open api schema for everything. Add also case where interface…

1ba7a4e

… extends interface.

add warn logs when x-kotlin-implements-fields is used without x-kotli…

3d78287

…n-implements to improve usability

Picazsoo force-pushed the feat/implement-x-implements-for-kotlin-spring branch from c7ba56c to 3d78287 Compare September 15, 2025 08:37

Picazsoo added 2 commits September 15, 2025 10:52

remove unnecessary generated files

fb35015

remove unnecessary generated files

3086ce8

remove "status" inner enum from Pet as it fails to properly import as…

212d2cc

… Pet.Status in implementations. This is a separate bug - not caused by x-kotlin-implements

Picazsoo force-pushed the feat/implement-x-implements-for-kotlin-spring branch from 3da9b01 to 212d2cc Compare September 15, 2025 15:18

wing328 merged commit 6278512 into OpenAPITools:master Sep 15, 2025
48 checks passed

Mattias-Sehlstedt mentioned this pull request Sep 24, 2025

[Kotlin] [Client] Add support for x-kotlin-implements and x-kotlin-implements-fields #22024

Closed

6 tasks

wing328 added this to the 7.16.0 milestone Sep 28, 2025

		){{/discriminator}}{{! no newline
		}}{{#parent}} : {{{.}}}{{! no newline

		x-kotlin-implements: [ 'com.some.package.Named' ]
		x-kotlin-implements-fields: [ name ]

Uh oh!

[kotlin-spring][server] Feat: Allow implementation of arbitrary interface in DTOs (similar to x-implements from java-spring) #21950

[kotlin-spring][server] Feat: Allow implementation of arbitrary interface in DTOs (similar to x-implements from java-spring) #21950

Uh oh!

Conversation

Picazsoo commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Picazsoo Sep 12, 2025 • 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!

Picazsoo Sep 11, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

wing328 commented Sep 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Picazsoo commented Sep 15, 2025

Uh oh!

Picazsoo commented Sep 15, 2025

Uh oh!

wing328 commented Sep 15, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Picazsoo commented Sep 11, 2025 •

edited

Loading

Picazsoo Sep 12, 2025 •

edited

Loading

Picazsoo Sep 11, 2025 •

edited

Loading