Add examples parameter in @Schema annotation for OAS 3.1 spec

Author: peter-em

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

@@ -98,6 +98,11 @@ public class CodegenProperty implements Cloneable, IJsonSchemaValidationProperti
      */
     @Getter @Setter
     public String example;
+    /**
+     * A free-form property to include a list of examples of an instance for this schema.
+     */
+    @Getter @Setter
+    public List<String> examples;
 
     @Getter @Setter
     public String jsonSchema;
@@ -615,6 +620,9 @@ public CodegenProperty clone() {
             if (this.allowableValues != null) {
                 cp.allowableValues = new HashMap<String, Object>(this.allowableValues);
             }
+            if (this.examples != null) {
+                cp.examples = new ArrayList<String>(this.examples);
+            }
             if (this.items != null) {
                 cp.items = this.items;
             }
@@ -996,6 +1004,7 @@ public String toString() {
         sb.append(", minLength=").append(minLength);
         sb.append(", pattern='").append(pattern).append('\'');
         sb.append(", example='").append(example).append('\'');
+        sb.append(", examples=").append(examples);
         sb.append(", jsonSchema='").append(jsonSchema).append('\'');
         sb.append(", minimum='").append(minimum).append('\'');
         sb.append(", maximum='").append(maximum).append('\'');
@@ -1183,6 +1192,7 @@ public boolean equals(Object o) {
                 Objects.equals(minLength, that.minLength) &&
                 Objects.equals(pattern, that.pattern) &&
                 Objects.equals(example, that.example) &&
+                Objects.equals(examples, that.examples) &&
                 Objects.equals(jsonSchema, that.jsonSchema) &&
                 Objects.equals(minimum, that.minimum) &&
                 Objects.equals(maximum, that.maximum) &&
@@ -1213,7 +1223,7 @@ public int hashCode() {
         return Objects.hash(openApiType, baseName, complexType, getter, setter, description,
                 dataType, datatypeWithEnum, dataFormat, name, min, max, defaultValue,
                 defaultValueWithParam, baseType, containerType, containerTypeMapped, title, unescapedDescription,
-                maxLength, minLength, pattern, example, jsonSchema, minimum, maximum,
+                maxLength, minLength, pattern, example, examples, jsonSchema, minimum, maximum,
                 exclusiveMinimum, exclusiveMaximum, required, deprecated,
                 isPrimitiveType, isModel, isContainer, isString, isNumeric,
                 isInteger, isLong, isNumber, isFloat, isDouble, isDecimal, isByteArray, isBinary, isFile,

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

@@ -25,6 +25,7 @@
 import com.samskivert.mustache.Mustache;
 import com.samskivert.mustache.Mustache.Compiler;
 import com.samskivert.mustache.Mustache.Lambda;
+import com.fasterxml.jackson.databind.JsonNode;
 import io.swagger.v3.core.util.Json;
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.Operation;
@@ -2559,6 +2560,45 @@ public String toExampleValue(Schema schema) {
         return "null";
     }
 
+    /**
+     * Return the list of example values of the property.
+     * <p>
+     * This method should be overridden in the generator to meet its requirement.
+     *
+     * @param schema Property schema
+     * @return a string list of the example values of the property
+     */
+    public List<String> toExampleValues(Schema schema) {
+        List<?> schemaExamples = schema.getExamples();
+        if (schemaExamples == null || schemaExamples.isEmpty()) {
+            return null;
+        }
+        List<String> examples = schemaExamples.stream()
+                    .map(this::getExampleValueString)
+                    .collect(Collectors.toList());
+
+        return examples.isEmpty() ? null : examples;
+    }
+
+    /**
+     * Return the string presentation of a single example value.
+     * <p>
+     * For value nodes, {@link JsonNode#asText()} is used to get the string without duplicated quotes.
+     *
+     * @param example the raw example value coming from the parsed schema
+     * @return string presentation of the example value
+     */
+    protected String getExampleValueString(Object example) {
+        if (example == null) {
+            return "null";
+        }
+        if (example instanceof JsonNode) {
+            JsonNode node = (JsonNode) example;
+            return node.isValueNode() ? node.asText() : node.toString();
+        }
+        return example.toString();
+    }
+
     /**
      * Return the default value of the property
      * <p>
@@ -4285,9 +4325,19 @@ public CodegenProperty fromProperty(String name, Schema p, boolean required, boo
         try {
             property.example = toExampleValue(p);
         } catch (Exception e) {
-            LOGGER.error("Error in generating `example` for the property {}. Default to ERROR_TO_EXAMPLE_VALUE. Enable debugging for more info.", property.baseName);
-            LOGGER.debug("Exception from toExampleValue: {}", e.getMessage());
-            property.example = "ERROR_TO_EXAMPLE_VALUE";
+            property.example = handleExampleException(property.baseName, e);
+        }
+
+        if (p.getExamples() != null) {
+            List<String> examples = new ArrayList<>();
+            for (Object example : p.getExamples()) {
+                try {
+                    examples.add(getExampleValueString(example));
+                } catch (Exception e) {
+                    examples.add(handleExampleException(property.baseName, e));
+                }
+            }
+            property.examples = examples;
         }
 
         property.jsonSchema = Json.pretty(Json.mapper().convertValue(p, TreeMap.class));
@@ -4512,6 +4562,9 @@ public CodegenProperty fromProperty(String name, Schema p, boolean required, boo
             if (original.getExample() != null) {
                 property.example = toExampleValue(original);
             }
+            if (original.getExamples() != null) {
+                property.examples = toExampleValues(original);
+            }
         }
 
         // override defaultValue if it's not set and defaultToEmptyContainer is set
@@ -4528,6 +4581,12 @@ public CodegenProperty fromProperty(String name, Schema p, boolean required, boo
         return property;
     }
 
+    private String handleExampleException(String propertyName, Exception e) {
+        LOGGER.error("Error in generating `example` for the property {}. Default to ERROR_TO_EXAMPLE_VALUE. Enable debugging for more info.", propertyName);
+        LOGGER.debug("Exception from toExampleValue: {}", e.getMessage());
+        return "ERROR_TO_EXAMPLE_VALUE";
+    }
+
     /**
      * update container's default to empty container according rules provided by the user.
      *

modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache

@@ -231,7 +231,7 @@ public {{>sealed}}class {{classname}}{{#parent}} extends {{{parent}}}{{/parent}}
   {{#lambda.trim}}{{>notNull}}{{/lambda.trim}}
   {{/useBeanValidation}}
   {{#swagger2AnnotationLibrary}}
-  @Schema(name = "{{{baseName}}}"{{#isReadOnly}}, accessMode = Schema.AccessMode.READ_ONLY{{/isReadOnly}}{{#example}}, example = "{{{.}}}"{{/example}}{{#description}}, description = "{{{.}}}"{{/description}}{{#deprecated}}, deprecated = true{{/deprecated}}, requiredMode = {{#required}}Schema.RequiredMode.REQUIRED{{/required}}{{^required}}Schema.RequiredMode.NOT_REQUIRED{{/required}}{{#isNullable}}, nullable = true{{/isNullable}})
+  @Schema(name = "{{{baseName}}}"{{#isReadOnly}}, accessMode = Schema.AccessMode.READ_ONLY{{/isReadOnly}}{{#example}}, example = "{{{.}}}"{{/example}}{{#examples.0}}, examples = { {{#examples}}"{{{.}}}"{{^-last}}, {{/-last}}{{/examples}} }{{/examples.0}}{{#description}}, description = "{{{.}}}"{{/description}}{{#deprecated}}, deprecated = true{{/deprecated}}, requiredMode = {{#required}}Schema.RequiredMode.REQUIRED{{/required}}{{^required}}Schema.RequiredMode.NOT_REQUIRED{{/required}}{{#isNullable}}, nullable = true{{/isNullable}})
   {{/swagger2AnnotationLibrary}}
   {{#swagger1AnnotationLibrary}}
   @ApiModelProperty({{#example}}example = "{{{.}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}{{#isReadOnly}}readOnly = {{{isReadOnly}}}, {{/isReadOnly}}value = "{{{description}}}")

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

@@ -2296,6 +2296,23 @@ public void testAllOfSingleRefSiblingExample() {
         assertEquals("Ref-Property-Example", codegen.fromProperty("refProperty", (Schema) testProperties.get("refProperty")).example);
     }
 
+    @Test
+    public void testOas31SchemaExamplesHandling() {
+        final OpenAPI openAPI = TestUtils.parseSpec("src/test/resources/3_1/issue_24755.yaml");
+        final DefaultCodegen codegen = new DefaultCodegen();
+        codegen.setOpenAPI(openAPI);
+
+        final Map properties = openAPI.getComponents().getSchemas().get("Pet").getProperties();
+
+        assertThat(codegen.fromProperty("name", (Schema) properties.get("name")).examples)
+                .containsExactly("Fluffy", "Rex");
+        assertThat(codegen.fromProperty("age", (Schema) properties.get("age")).examples)
+                .containsExactly("3");
+        assertThat(codegen.fromProperty("tags", (Schema) properties.get("tags")).examples)
+                .containsExactly("[\"a\",\"b\"]");
+        assertNull(codegen.fromProperty("height", (Schema) properties.get("height")).examples);
+    }
+
     @Test
     public void testDeprecatedRef() {
         final OpenAPI openAPI = TestUtils.parseSpec("src/test/resources/3_0/model-deprecated.yaml");

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

@@ -10203,4 +10203,17 @@ void listItems_with_additionalItemsAnnotations() throws IOException {
                 "private List<@NotNull @Min(0)Integer> listInteger",
                 "private List<@NotNull @Size(max=10) String> listCode");
     }
+
+    @Test
+    public void shouldRenderOas31SchemaExamples() throws IOException {
+        Map<String, File> files = generateFromContract("src/test/resources/3_1/issue_24755.yaml", SPRING_BOOT);
+
+        JavaFileAssert.assertThat(files.get("Pet.java"))
+                .fileContains(
+                        "example = \"Fluffy\"",
+                        "examples = { \"Fluffy\", \"Rex\" }",
+                        "examples = { \"3\" }",
+                        "examples = { \"[a, b]\" }"
+                ).fileDoesNotContain("examples = {}");
+    }
 }

modules/openapi-generator/src/test/resources/3_1/issue_24755.yaml

@@ -0,0 +1,41 @@
+openapi: 3.1.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      operationId: listPets
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Pet'
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        name:
+          type: string
+          example: 'Fluffy'
+          examples:
+            - 'Fluffy'
+            - 'Rex'
+        age:
+          type: integer
+          examples:
+            - 3
+        height:
+          type: integer
+          examples: []
+        tags:
+          type: array
+          items:
+            type: string
+          examples:
+            - ['a', 'b']