fix (JAVA): example in README for useOneOfInterfaces (#17419)

Author: Nicklas2751

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

@@ -291,6 +291,9 @@ apiTemplateFiles are for API outputs only (controllers/handlers).
     // whether or not the oneOf imports machinery should add oneOf interfaces as imports in implementing classes
     protected boolean addOneOfInterfaceImports = false;
     protected List<CodegenModel> addOneOfInterfaces = new ArrayList<>();
+    // set of all classnames that are oneOf interfaces (both synthetic property-level and component-level)
+    // populated during preprocessOpenAPI(), used by setParameterExampleValue() to avoid "new InterfaceType()"
+    protected Set<String> oneOfInterfaceNames = new HashSet<>();
 
     // flag to indicate whether to only update files whose contents have changed
     protected boolean enableMinimalUpdate = false;
@@ -1084,6 +1087,7 @@ public void preprocessOpenAPI(OpenAPI openAPI) {
                     } else {
                         // else this is a component schema, so we will just use that as the oneOf interface model
                         addOneOfNameExtension(s, n);
+                        oneOfInterfaceNames.add(n);
                     }
                 } else if (ModelUtils.isArraySchema(s)) {
                     Schema items = ModelUtils.getSchemaItems(s);
@@ -8491,6 +8495,7 @@ public void addOneOfInterfaceModel(Schema cs, String type) {
         cm.interfaceModels = new ArrayList<>();
 
         addOneOfInterfaces.add(cm);
+        oneOfInterfaceNames.add(type);
     }
 
     public void addImportsToOneOfInterface(List<Map<String, String>> imports) {

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

@@ -1728,7 +1728,13 @@ public void setParameterExampleValue(CodegenParameter p) {
             example = type + ".fromValue(\"" + example + "\")";
         } else if (!languageSpecificPrimitives.contains(type)) {
             // type is a model class, e.g. User
-            example = "new " + type + "()";
+            // if useOneOfInterfaces is enabled and the type is a generated oneOf interface,
+            // we cannot instantiate it with 'new', so we use null instead
+            if (useOneOfInterfaces && oneOfInterfaceNames.contains(type)) {
+                example = "null";
+            } else {
+                example = "new " + type + "()";
+            }
         }
 
         if (example == null) {

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

@@ -3897,4 +3897,33 @@ public void testOkHttpGsonClientWithUseOneOfInterfaceShouldntRegisterInterfaceAs
         );
     }
 
+    @Test(dataProvider = "allJavaClients")
+    public void testClientWithUseOneOfInterfaceShouldntInstantiateInterfaceInApiDoc_issue_17419(String client) {
+        // given
+        final Path output = newTempFolder();
+        final CodegenConfigurator configurator = new CodegenConfigurator()
+                .setGeneratorName("java")
+                .setLibrary(client)
+                .setAdditionalProperties(Map.of("useOneOfInterfaces", "true"))
+                .setInputSpec("src/test/resources/bugs/issue_17419_readme.yaml")
+                .setOutputDir(output.toString().replace("\\", "/"));
+
+        final ClientOptInput input = configurator.toClientOptInput();
+
+        // when
+        List<File> files = new DefaultGenerator().opts(input).generate();
+
+        // then
+        validateJavaSourceFiles(files);
+
+        // In every generated Markdown file (README.md, api_doc, etc.) the example for a
+        // oneOf interface parameter must not contain "new MyOperationRequest()" since
+        // interfaces cannot be instantiated with 'new'.
+        files.stream()
+                .filter(f -> f.getName().endsWith(".md"))
+                .forEach(f -> TestUtils.assertFileNotContains(f.toPath(),
+                        "new MyOperationRequest()"
+                ));
+    }
+
 }

modules/openapi-generator/src/test/resources/bugs/issue_17419_readme.yaml

@@ -0,0 +1,36 @@
+openapi: 3.0.0
+info:
+  title: OneOf interface README bug
+  version: '1.0'
+servers:
+  - url: 'http://localhost:8080'
+paths:
+  '/myapi/myendpoint':
+    post:
+      operationId: myOperation
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MyOperationRequest'
+      responses:
+        '200':
+          description: OK
+components:
+  schemas:
+    MyOperationRequest:
+      oneOf:
+        - $ref: '#/components/schemas/VariantA'
+        - $ref: '#/components/schemas/VariantB'
+    VariantA:
+      type: object
+      properties:
+        fieldA:
+          type: string
+    VariantB:
+      type: object
+      properties:
+        fieldB:
+          type: integer
+

pom.xml

@@ -1232,7 +1232,7 @@
         <junit.version>5.10.2</junit.version>
         <kotlin.version>1.6.21</kotlin.version>
         <kotlin-compiler-embeddable.version>1.6.21</kotlin-compiler-embeddable.version>
-        <lombok.version>1.18.30</lombok.version>
+        <lombok.version>1.18.38</lombok.version>
         <maven-dependency-plugin.version>3.8.1</maven-dependency-plugin.version>
         <maven-compiler-plugin.version>3.14.0</maven-compiler-plugin.version>
         <maven-jar-plugin.version>3.4.2</maven-jar-plugin.version>