[jaxrs-spec] Support useRecords

Adds a useRecords option to the jaxrs-spec generator. When useRecords=true, the
concrete subtypes that implement a generated oneOf interface render as Java
records instead of mutable classes.

- JavaJAXRSSpecServerCodegen: useRecords option, and postProcessAllModels marks
  record-eligible implementors with x-jaxrs-record (no parent, no additional
  properties, implements a generated oneOf interface).
- record.mustache renders the record; model.mustache routes x-jaxrs-record to it.
- oneof_interface.mustache declares the discriminator accessor in record style
  (petType()) under useRecords so records satisfy the interface via their
  canonical accessors; sealed.mustache no longer marks a record final.
- pom.mustache bumps java.version to 17 when useRecords (records need JDK 16+).
- Adds testOneOfRecordImplementationGeneration and a jaxrs-spec-records sample
  (registered in the JDK17 samples workflow).

useRecords is independent of useSealed. The feature stays opt-in; default
jaxrs-spec output is unchanged.

Author: Ignacio-Vidal

.github/workflows/samples-jdk17.yaml

@@ -23,6 +23,7 @@ on:
       - samples/server/petstore/java-helidon-server/v3/mp/**
       - samples/server/petstore/java-helidon-server/v3/se/**
       - samples/server/petstore/jaxrs-spec-sealed/**
+      - samples/server/petstore/jaxrs-spec-records/**
   pull_request:
     paths:
       # clients
@@ -46,6 +47,7 @@ on:
       - samples/server/petstore/java-helidon-server/v3/mp/**
       - samples/server/petstore/java-helidon-server/v3/se/**
       - samples/server/petstore/jaxrs-spec-sealed/**
+      - samples/server/petstore/jaxrs-spec-records/**
 jobs:
   build:
     name: Build with JDK17
@@ -75,6 +77,7 @@ jobs:
           - samples/server/petstore/java-helidon-server/v3/mp/
           - samples/server/petstore/java-helidon-server/v3/se
           - samples/server/petstore/jaxrs-spec-sealed
+          - samples/server/petstore/jaxrs-spec-records
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-java@v5

bin/configs/jaxrs-spec-records.yaml

@@ -0,0 +1,11 @@
+generatorName: jaxrs-spec
+outputDir: samples/server/petstore/jaxrs-spec-records
+inputSpec: modules/openapi-generator/src/test/resources/3_0/jaxrs-spec/oneof_interface.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaJaxRS/spec
+additionalProperties:
+  artifactId: jaxrs-spec-records-petstore-server
+  useOneOfInterfaces: "true"
+  useSealed: "true"
+  useRecords: "true"
+  serializableModel: "true"
+  hideGenerationTimestamp: "true"

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSSpecServerCodegen.java

@@ -34,8 +34,10 @@
 import java.io.File;
 import java.util.Collection;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 
 import static org.openapitools.codegen.languages.features.GzipFeatures.USE_GZIP_FEATURE;
 
@@ -60,6 +62,7 @@ public class JavaJAXRSSpecServerCodegen extends AbstractJavaJAXRSServerCodegen {
     public static final String USE_JAKARTA_SECURITY_ANNOTATIONS = "useJakartaSecurityAnnotations";
     public static final String USE_ENUM_CASE_INSENSITIVE = "useEnumCaseInsensitive";
     public static final String USE_SEALED = "useSealed";
+    public static final String USE_RECORDS = "useRecords";
 
     public static final String QUARKUS_LIBRARY = "quarkus";
     public static final String THORNTAIL_LIBRARY = "thorntail";
@@ -83,6 +86,9 @@ public class JavaJAXRSSpecServerCodegen extends AbstractJavaJAXRSServerCodegen {
     @Setter
     protected boolean useSealed = false;
 
+    @Setter
+    protected boolean useRecords = false;
+
     private final JakartaSecurityAnnotationProcessor jakartaSecurityAnnotationProcessor = new JakartaSecurityAnnotationProcessor();
 
     @Getter @Setter
@@ -167,6 +173,7 @@ public JavaJAXRSSpecServerCodegen() {
         cliOptions.add(CliOption.newBoolean(GENERATE_JSON_CREATOR, "Whether to generate @JsonCreator constructor for required properties.", generateJsonCreator));
         cliOptions.add(CliOption.newBoolean(USE_ENUM_CASE_INSENSITIVE, "Use `equalsIgnoreCase` when String for enum comparison", useEnumCaseInsensitive));
         cliOptions.add(CliOption.newBoolean(USE_SEALED, "Whether to generate sealed model interfaces and classes.", useSealed));
+        cliOptions.add(CliOption.newBoolean(USE_RECORDS, "Whether to render the implementations of a generated oneOf interface (useOneOfInterfaces=true) as Java records instead of classes.", useRecords));
     }
 
     @Override
@@ -211,6 +218,7 @@ public void processOpts() {
         convertPropertyToBooleanAndWriteBack(GENERATE_JSON_CREATOR, this::setGenerateJsonCreator);
         convertPropertyToBooleanAndWriteBack(USE_ENUM_CASE_INSENSITIVE, this::setUseEnumCaseInsensitive);
         convertPropertyToBooleanAndWriteBack(USE_SEALED, this::setUseSealed);
+        convertPropertyToBooleanAndWriteBack(USE_RECORDS, this::setUseRecords);
 
         if (additionalProperties.containsKey(OPEN_API_SPEC_FILE_LOCATION)) {
             openApiSpecFileLocation = additionalProperties.get(OPEN_API_SPEC_FILE_LOCATION).toString();
@@ -400,16 +408,20 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
     public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs) {
         Map<String, ModelsMap> result = super.postProcessAllModels(objs);
 
-        // Index the discriminators of the generated oneOf interfaces by classname. A child of a oneOf
-        // interface (useOneOfInterfaces) inherits a shared base via allOf and therefore has no Java
-        // parentModel carrying the discriminator - the discriminator lives on the interface it implements.
+        // Collect, for the interfaces generated by the useOneOfInterfaces feature: their classnames (to
+        // identify which concrete models implement one of them and are therefore record candidates) and
+        // their discriminators indexed by classname (a child of a oneOf interface inherits a shared base
+        // via allOf and has no Java parentModel carrying the discriminator - it lives on the interface).
+        Set<String> oneOfInterfaceNames = new HashSet<>();
         Map<String, CodegenDiscriminator> oneOfInterfaceDiscriminators = new HashMap<>();
         for (ModelsMap modelsMap : result.values()) {
             for (ModelMap modelMap : modelsMap.getModels()) {
                 CodegenModel model = modelMap.getModel();
-                if (Boolean.TRUE.equals(model.getVendorExtensions().get("x-is-one-of-interface"))
-                        && model.getDiscriminator() != null) {
-                    oneOfInterfaceDiscriminators.put(model.classname, model.getDiscriminator());
+                if (Boolean.TRUE.equals(model.getVendorExtensions().get("x-is-one-of-interface"))) {
+                    oneOfInterfaceNames.add(model.classname);
+                    if (model.getDiscriminator() != null) {
+                        oneOfInterfaceDiscriminators.put(model.classname, model.getDiscriminator());
+                    }
                 }
             }
         }
@@ -437,6 +449,9 @@ public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs)
                 if (useSealed && !Boolean.TRUE.equals(model.getVendorExtensions().get("x-is-one-of-interface"))) {
                     model.permits.removeAll(model.oneOf);
                 }
+                if (useRecords && isOneOfInterfaceRecordCandidate(model, oneOfInterfaceNames)) {
+                    model.getVendorExtensions().put("x-jaxrs-record", true);
+                }
             }
         }
         return result;
@@ -463,6 +478,32 @@ private CodegenDiscriminator discriminatorOfImplementedOneOfInterface(
         return null;
     }
 
+    /**
+     * A concrete model is rendered as a record only when it implements a oneOf interface produced by the
+     * useOneOfInterfaces feature, and it is structurally record-compatible: it has no Java parent (records
+     * cannot extend) and no additional (undeclared) properties (those require a mutable map-backed pojo).
+     *
+     * @param model               the concrete model that may implement a oneOf interface
+     * @param oneOfInterfaceNames the classnames of the generated oneOf interfaces
+     * @return {@code true} when the model should be rendered as a record
+     */
+    @SuppressWarnings("unchecked")
+    private boolean isOneOfInterfaceRecordCandidate(CodegenModel model, Set<String> oneOfInterfaceNames) {
+        if (model.getParent() != null || model.getAdditionalPropertiesType() != null) {
+            return false;
+        }
+        Object implementsExtension = model.getVendorExtensions().get("x-implements");
+        if (!(implementsExtension instanceof Collection)) {
+            return false;
+        }
+        for (Object intf : (Collection<Object>) implementsExtension) {
+            if (oneOfInterfaceNames.contains(String.valueOf(intf))) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     @Override
     public CodegenOperation fromOperation(String path, String httpMethod, Operation operation, List<Server> servers) {
         CodegenOperation op = super.fromOperation(path, httpMethod, operation, servers);

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/model.mustache

@@ -16,6 +16,6 @@ import {{javaxPackage}}.validation.Valid;
 {{>enumOuterClass}}
 
 {{/isEnum}}
-{{^isEnum}}{{#vendorExtensions.x-is-one-of-interface}}{{>oneof_interface}}{{/vendorExtensions.x-is-one-of-interface}}{{^vendorExtensions.x-is-one-of-interface}}{{>pojo}}{{/vendorExtensions.x-is-one-of-interface}}{{/isEnum}}
+{{^isEnum}}{{#vendorExtensions.x-is-one-of-interface}}{{>oneof_interface}}{{/vendorExtensions.x-is-one-of-interface}}{{^vendorExtensions.x-is-one-of-interface}}{{#vendorExtensions.x-jaxrs-record}}{{>record}}{{/vendorExtensions.x-jaxrs-record}}{{^vendorExtensions.x-jaxrs-record}}{{>pojo}}{{/vendorExtensions.x-jaxrs-record}}{{/vendorExtensions.x-is-one-of-interface}}{{/isEnum}}
 {{/model}}
 {{/models}}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/oneof_interface.mustache

@@ -16,6 +16,6 @@
 
 public {{>sealed}}interface {{classname}}{{#vendorExtensions.x-implements}}{{#-first}} extends {{{.}}}{{/-first}}{{^-first}}, {{{.}}}{{/-first}}{{/vendorExtensions.x-implements}} {{>permits}}{
     {{#discriminator}}
-    {{propertyType}} {{propertyGetter}}();
+    {{propertyType}} {{#useRecords}}{{propertyName}}{{/useRecords}}{{^useRecords}}{{propertyGetter}}{{/useRecords}}();
     {{/discriminator}}
 }

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/pom.mustache

@@ -184,7 +184,7 @@
     {{/openApiNullable}}
   </dependencies>
   <properties>
-    <java.version>{{#useSealed}}17{{/useSealed}}{{^useSealed}}1.8{{/useSealed}}</java.version>
+    <java.version>{{#useSealed}}17{{/useSealed}}{{^useSealed}}{{#useRecords}}17{{/useRecords}}{{^useRecords}}1.8{{/useRecords}}{{/useSealed}}</java.version>
     <maven.compiler.source>${java.version}</maven.compiler.source>
     <maven.compiler.target>${java.version}</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/record.mustache

@@ -0,0 +1,64 @@
+{{#useSwaggerAnnotations}}
+import io.swagger.annotations.*;
+{{/useSwaggerAnnotations}}
+{{#useSwaggerV3Annotations}}
+import io.swagger.v3.oas.annotations.media.Schema;
+{{/useSwaggerV3Annotations}}
+{{#jackson}}
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonValue;
+import com.fasterxml.jackson.annotation.JsonTypeName;
+{{/jackson}}
+{{#withXml}}
+import {{javaxPackage}}.xml.bind.annotation.XmlElement;
+import {{javaxPackage}}.xml.bind.annotation.XmlRootElement;
+import {{javaxPackage}}.xml.bind.annotation.XmlAccessType;
+import {{javaxPackage}}.xml.bind.annotation.XmlAccessorType;
+import {{javaxPackage}}.xml.bind.annotation.XmlType;
+import {{javaxPackage}}.xml.bind.annotation.XmlEnum;
+import {{javaxPackage}}.xml.bind.annotation.XmlEnumValue;
+{{/withXml}}
+
+{{#discriminator}}{{>typeInfoAnnotation}}{{/discriminator}}{{#description}}/**
+ * {{.}}
+ {{#isDeprecated}}
+ * @deprecated
+ {{/isDeprecated}}
+ **/{{/description}}
+{{#isDeprecated}}
+@Deprecated
+
+{{/isDeprecated}}{{#useSwaggerAnnotations}}{{#description}}@ApiModel(description = "{{{.}}}"){{/description}}{{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+@Schema({{#title}}title="{{{.}}}", {{/title}}{{#description}}description="{{{.}}}"{{/description}}{{^description}}description=""{{/description}}{{#isDeprecated}}, deprecated = true{{/isDeprecated}}){{/useSwaggerV3Annotations}}{{#useMicroProfileOpenAPIAnnotations}}
+@org.eclipse.microprofile.openapi.annotations.media.Schema({{#title}}title="{{{.}}}", {{/title}}{{#description}}description="{{{.}}}"{{/description}}{{^description}}description=""{{/description}}{{#isDeprecated}}, deprecated = true{{/isDeprecated}}){{/useMicroProfileOpenAPIAnnotations}}
+{{#jackson}}
+@JsonTypeName("{{#vendorExtensions.x-discriminator-value}}{{{vendorExtensions.x-discriminator-value}}}{{/vendorExtensions.x-discriminator-value}}{{^vendorExtensions.x-discriminator-value}}{{name}}{{/vendorExtensions.x-discriminator-value}}")
+{{/jackson}}
+{{>generatedAnnotation}}{{>additionalModelTypeAnnotations}}
+{{#vendorExtensions.x-class-extra-annotation}}
+{{{vendorExtensions.x-class-extra-annotation}}}
+{{/vendorExtensions.x-class-extra-annotation}}
+public {{>sealed}}record {{classname}}(
+  {{#vars}}
+  {{#vendorExtensions.x-field-extra-annotation}}
+  {{{.}}}
+  {{/vendorExtensions.x-field-extra-annotation}}
+  {{#deprecated}}
+  @Deprecated
+  {{/deprecated}}
+  {{#jackson}}@JsonProperty({{#required}}required = {{required}}, value = {{/required}}"{{baseName}}") {{/jackson}}{{#useBeanValidation}}{{>beanValidation}}{{/useBeanValidation}}{{{datatypeWithEnum}}} {{name}}{{^-last}},{{/-last}}
+  {{/vars}}
+) {{#vendorExtensions.x-implements}}{{#-first}}implements {{{.}}}{{/-first}}{{^-first}}, {{{.}}}{{/-first}}{{/vendorExtensions.x-implements}} {
+  {{#vars}}
+  {{#isEnum}}
+  {{^isContainer}}
+  {{>enumClass}}{{! prevent indent}}
+  {{/isContainer}}
+  {{#isContainer}}
+  {{#mostInnerItems}}
+  {{>enumClass}}{{! prevent indent}}
+  {{/mostInnerItems}}
+  {{/isContainer}}
+  {{/isEnum}}
+  {{/vars}}
+}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/sealed.mustache

@@ -1 +1 @@
-{{#useSealed}}{{#permits.0}}sealed {{/permits.0}}{{^permits.0}}{{^vendorExtensions.x-is-one-of-interface}}final {{/vendorExtensions.x-is-one-of-interface}}{{/permits.0}}{{/useSealed}}
+{{#useSealed}}{{#permits.0}}sealed {{/permits.0}}{{^permits.0}}{{^vendorExtensions.x-is-one-of-interface}}{{^vendorExtensions.x-jaxrs-record}}final {{/vendorExtensions.x-jaxrs-record}}{{/vendorExtensions.x-is-one-of-interface}}{{/permits.0}}{{/useSealed}}

modules/openapi-generator/src/test/java/org/openapitools/codegen/java/jaxrs/JavaJAXRSSpecServerCodegenTest.java

@@ -1532,6 +1532,63 @@ public void testWithoutUseSealedOutputIsUnchanged() throws Exception {
         assertFileContains(Paths.get(outputDir + "/pom.xml"), "<java.version>1.8</java.version>");
     }
 
+    /**
+     * With {@code useRecords=true} the concrete subtypes of a generated oneOf interface render as Java
+     * records rather than mutable classes. Because a record component {@code petType} exposes the
+     * canonical accessor {@code petType()} (not {@code getPetType()}), the interface declares the
+     * discriminator accessor in record style so the records satisfy it without bridge methods. The
+     * record components carry the {@code @JsonProperty} annotations. Combined here with
+     * {@code useSealed=true} so the interface is also sealed and permits the record subtypes.
+     */
+    @Test
+    public void testOneOfRecordImplementationGeneration() throws Exception {
+        File output = Files.createTempDirectory("test").toFile().getCanonicalFile();
+        output.deleteOnExit();
+
+        Map<String, Object> properties = new HashMap<>();
+        properties.put("useOneOfInterfaces", "true");
+        properties.put("useSealed", "true");
+        properties.put("useRecords", "true");
+
+        final CodegenConfigurator configurator = new CodegenConfigurator()
+                .setGeneratorName("jaxrs-spec")
+                .setAdditionalProperties(properties)
+                .setInputSpec("src/test/resources/3_0/jaxrs-spec/oneof_interface.yaml")
+                .setOutputDir(output.getAbsolutePath().replace("\\", "/"));
+
+        DefaultGenerator generator = new DefaultGenerator();
+        generator.opts(configurator.toClientOptInput()).generate();
+
+        // assertFileContains is used rather than JavaFileAssert because the latter parses the source
+        // with a JavaParser language level that predates sealed/record types.
+        String modelDir = output.getAbsolutePath().replace("\\", "/") + "/src/gen/java/org/openapitools/model/";
+
+        // The interface is sealed, permits the record subtypes, and declares the discriminator accessor
+        // in record style (petType(), not getPetType()) so the records implement it via their canonical
+        // accessors.
+        assertFileContains(Paths.get(modelDir + "PetRequest.java"),
+                "public sealed interface PetRequest",
+                "permits CatRequest, DogRequest",
+                "PetType petType();");
+        assertFileNotContains(Paths.get(modelDir + "PetRequest.java"), "getPetType");
+
+        // The concrete subtypes are records implementing (not extending) the interface, with @JsonProperty
+        // on the components and no JavaBean getters or final-class declaration.
+        assertFileContains(Paths.get(modelDir + "CatRequest.java"),
+                "public record CatRequest(",
+                "@JsonProperty(required = true, value = \"petType\")",
+                "PetType petType",
+                "implements PetRequest");
+        assertFileNotContains(Paths.get(modelDir + "CatRequest.java"),
+                "class CatRequest", "extends PetRequest", "public PetType getPetType()");
+
+        assertFileContains(Paths.get(modelDir + "DogRequest.java"),
+                "public record DogRequest(",
+                "implements PetRequest");
+        assertFileNotContains(Paths.get(modelDir + "DogRequest.java"),
+                "class DogRequest", "extends PetRequest");
+    }
+
     @Test
     public void testGenerateJsonNullableListFieldsHelperMethodReferences_issue23251() throws Exception {
         Map<String, Object> properties = new HashMap<>();

samples/server/petstore/jaxrs-spec-records/.openapi-generator-ignore

@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md