Support for openapi v3/v3.1 schema formats #1291

springwolf-add-ons/springwolf-json-schema/src/test/java/io/github/springwolf/addons/json_schema/JsonSchemaGeneratorTest.java

@@ -11,6 +11,7 @@
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaReference;
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaType;
 import io.github.springwolf.core.asyncapi.schemas.SwaggerSchemaUtil;
+import io.github.springwolf.core.configuration.properties.PayloadSchemaFormat;
 import io.swagger.v3.core.util.Json;
 import io.swagger.v3.oas.models.media.ArraySchema;
 import io.swagger.v3.oas.models.media.BooleanSchema;
@@ -42,7 +43,8 @@ class JsonSchemaGeneratorTest {
     @MethodSource
     void validateJsonSchemaTest(String expectedJsonSchema, Supplier<Schema<?>> asyncApiSchema) throws Exception {
         // given
-        SchemaObject actualSchema = swaggerSchemaUtil.mapSchema(asyncApiSchema.get());
+        ComponentSchema actualSchema =
+                swaggerSchemaUtil.mapSchema(asyncApiSchema.get(), PayloadSchemaFormat.ASYNCAPI_V3);
 
         // when
         verifyValidJsonSchema(expectedJsonSchema);
@@ -67,7 +69,7 @@ void validateJsonSchemaTest(String expectedJsonSchema, Supplier<Schema<?>> async
                 ComponentSchema.of(pongSchema));
 
         // when
-        Object jsonSchema = jsonSchemaGenerator.fromSchema(ComponentSchema.of(actualSchema), definitions);
+        Object jsonSchema = jsonSchemaGenerator.fromSchema(actualSchema, definitions);
 
         // then
         String jsonSchemaString = mapper.writeValueAsString(jsonSchema);

springwolf-asyncapi/src/main/java/io/github/springwolf/asyncapi/v3/model/schema/MultiFormatSchema.java

@@ -49,4 +49,11 @@ public class MultiFormatSchema extends ExtendableObject {
      */
     @JsonProperty(value = "schema")
     private Object schema;
+
+    public static MultiFormatSchema of(Object schema) {
+        // if payloadSchema.payload is already an instance of MultiFormatSchema, do not wrap again.
+        return (schema instanceof MultiFormatSchema mfs)
+                ? mfs
+                : MultiFormatSchema.builder().schema(schema).build();
+    }
 }

springwolf-asyncapi/src/main/java/io/github/springwolf/asyncapi/v3/model/schema/SchemaFormat.java

@@ -12,6 +12,7 @@ public enum SchemaFormat {
     ASYNCAPI_V3_JSON("application/vnd.aai.asyncapi+json;version=" + AsyncAPI.ASYNCAPI_DEFAULT_VERSION),
     ASYNCAPI_V3_YAML("application/vnd.aai.asyncapi+yaml;version=" + AsyncAPI.ASYNCAPI_DEFAULT_VERSION),
     OPENAPI_V3("application/vnd.oai.openapi;version=3.0.0"),
+    OPENAPI_V3_1("application/vnd.oai.openapi;version=3.1.0"),
     OPENAPI_V3_JSON("application/vnd.oai.openapi+json;version=3.0.0"),
     OPENAPI_V3_YAML("application/vnd.oai.openapi+yaml;version=3.0.0"),
     JSON_SCHEMA_JSON("application/schema+json;version=draft-07"),

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/components/ComponentsService.java

@@ -6,6 +6,7 @@
 import io.github.springwolf.asyncapi.v3.model.channel.message.MessageReference;
 import io.github.springwolf.asyncapi.v3.model.components.ComponentSchema;
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaObject;
+import io.github.springwolf.asyncapi.v3.model.schema.SchemaReference;
 import io.github.springwolf.core.configuration.properties.SpringwolfConfigProperties;
 import jakarta.annotation.Nullable;
 
@@ -33,17 +34,17 @@ public interface ComponentsService {
      *
      * @param type        Type to resolve a schema from
      * @param contentType Runtime ContentType of Schema
-     * @return the root schema for the given type.
+     * @return a {@link SchemaReference} referencing the root schema, or null if no schema could be resolved.
      */
     @Nullable
     ComponentSchema resolvePayloadSchema(Type type, String contentType);
 
     /**
      * registers the given schema with this {@link ComponentsService}
-     * @param headers the schema to register, typically a header schema
+     * @param schemaWithoutRef the schema to register, typically a header schema
      * @return the title attribute of the given schema
      */
-    String registerSchema(SchemaObject headers);
+    String registerSchema(SchemaObject schemaWithoutRef);
 
     /**
      * Provides a map of all registered messages.

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/components/DefaultComponentsService.java

@@ -7,6 +7,7 @@
 import io.github.springwolf.asyncapi.v3.model.components.ComponentSchema;
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaObject;
 import io.github.springwolf.core.asyncapi.schemas.SwaggerSchemaService;
+import io.github.springwolf.core.configuration.properties.PayloadSchemaFormat;
 import io.github.springwolf.core.configuration.properties.SpringwolfConfigProperties;
 import lombok.AllArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -51,12 +52,14 @@ public Map<String, ComponentSchema> getSchemas() {
      *
      * @param type        Type to resolve a schema from
      * @param contentType Runtime ContentType of Schema
-     * @return the root schema for the given type.
+     * @return the root schema for the given type
      */
     @Override
     public ComponentSchema resolvePayloadSchema(Type type, String contentType) {
-
-        SwaggerSchemaService.ExtractedSchemas payload = schemaService.resolveSchema(type, contentType);
+        PayloadSchemaFormat payloadSchemaFormat =
+                springwolfConfigProperties.getDocket().getPayloadSchemaFormat();
+        SwaggerSchemaService.ExtractedSchemas payload =
+                schemaService.resolveSchema(type, contentType, payloadSchemaFormat);
         payload.referencedSchemas().forEach(schemas::putIfAbsent);
         return payload.rootSchema();
     }
@@ -65,21 +68,21 @@ public ComponentSchema resolvePayloadSchema(Type type, String contentType) {
      * registers the given schema with this {@link ComponentsService}.
      * <p>NOTE</p>
      * Use only with schemas with max. one level of properties. Providing {@link SchemaObject}s with deep
-     * property hierarchy will result in an corrupted result.
+     * property hierarchy will result in a corrupted result.
      * <br/>
-     * A typical usecase for this method is  registering of header schemas, which have typically a simple structure.
+     * A typical usecase for this method is registering of header schemas, which have typically a simple structure.
      *
-     * @param headers the schema to register, typically a header schema
+     * @param schemaWithoutRef the schema to register, typically a header schema
      * @return the title attribute of the given schema
      */
     @Override
-    public String registerSchema(SchemaObject headers) {
-        log.debug("Registering schema for {}", headers.getTitle());
+    public String registerSchema(SchemaObject schemaWithoutRef) {
+        log.debug("Registering schema for {}", schemaWithoutRef.getTitle());
 
-        SchemaObject headerSchema = schemaService.extractSchema(headers);
-        this.schemas.putIfAbsent(headers.getTitle(), ComponentSchema.of(headerSchema));
+        ComponentSchema processedSchema = schemaService.postProcessSchemaWithoutRef(schemaWithoutRef);
+        this.schemas.putIfAbsent(schemaWithoutRef.getTitle(), processedSchema);
 
-        return headers.getTitle();
+        return schemaWithoutRef.getTitle();
     }
 
     /**

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/components/examples/walkers/DefaultSchemaWalker.java

@@ -7,6 +7,7 @@
 import io.swagger.v3.oas.models.media.StringSchema;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.lang.Nullable;
 import org.springframework.util.CollectionUtils;
 
 import java.text.SimpleDateFormat;
@@ -175,7 +176,14 @@ private Optional<T> buildExampleFromUnvisitedSchema(
             return composedSchemaExample;
         }
 
-        String type = schema.getType();
+        // schema may be an openapi v3 or v3.1 schema. While v3 uses an simple 'type' field, v3.1 supports a set of
+        // types, for example ["string", "null"].
+
+        String type = getTypeForExampleValue(schema);
+        if (type == null) {
+            return Optional.empty();
+        }
+
         return switch (type) {
             case "array" -> buildArrayExample(schema, definitions, visited);
             case "boolean" -> exampleValueGenerator.createBooleanExample(DEFAULT_BOOLEAN_EXAMPLE, schema);
@@ -235,6 +243,33 @@ private String getFirstEnumValue(Schema schema) {
         return null;
     }
 
+    /**
+     * looks in schemas openapi-v3 'type' and openapi-v3.1 'types' fields to
+     * find the best candidate to use as an example value.
+     *
+     * @param schema
+     * @return the type to use for example values, or null if no suitable type was found.
+     */
+    @Nullable
+    String getTypeForExampleValue(Schema schema) {
+        // if the single type field is present, it has precedence over the types field
+        if (schema.getType() != null) {
+            return schema.getType();
+        }
+
+        Set<String> types = schema.getTypes();
+
+        if (types == null || types.isEmpty()) {
+            return null;
+        }
+
+        return types.stream()
+                .filter(t -> !"null".equals(t))
+                .sorted() // sort types to be deterministic
+                .findFirst()
+                .orElse(null);
+    }
+
     private Optional<T> buildFromComposedSchema(
             Optional<String> name, Schema schema, Map<String, Schema> definitions, Set<Schema> visited) {
         final List<Schema> schemasAllOf = schema.getAllOf();

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/grouping/GroupingService.java

@@ -203,7 +203,7 @@ private void markSchemas(AsyncAPI fullAsyncApi, MarkingContext markingContext, S
      * properties, allOf, anyOf, oneOf, not- and items references. Trys to deduce the schema id from the ref path and
      * returns a Set of detected schema ids.
      *
-     * @param markingContext the current {@link MarkingContext}
+     * @param markingContext  the current {@link MarkingContext}
      * @param componentSchema the {@link ComponentSchema} to analyze
      * @return Set of schema ids representing nested schema refs
      */
@@ -217,14 +217,16 @@ private static Set<String> findUnmarkedNestedSchemas(
         if (componentSchema.getMultiFormatSchema() != null) {
             MultiFormatSchema multiFormatSchema = componentSchema.getMultiFormatSchema();
 
-            // Currently we support async_api and open_api format.
+            // Currently we support async_api and open_api v3 and v3.1 format.
             // The concrete schemaformat mediatype can contain json/yaml postfix, so we check wether the begin of the
             // media type matches.
-            if (multiFormatSchema.getSchemaFormat().startsWith(SchemaFormat.ASYNCAPI_V3.toString())
+            String schemaFormat = multiFormatSchema.getSchemaFormat();
+            if (schemaFormat.startsWith(SchemaFormat.ASYNCAPI_V3.toString())
                     && multiFormatSchema.getSchema() instanceof SchemaObject schemaObject) {
                 return findUnmarkedNestedSchemasForAsyncAPISchema(markingContext, schemaObject);
             }
-            if (multiFormatSchema.getSchemaFormat().startsWith(SchemaFormat.OPENAPI_V3.toString())
+            if ((schemaFormat.startsWith(SchemaFormat.OPENAPI_V3.toString())
+                            || schemaFormat.startsWith(SchemaFormat.OPENAPI_V3_1.toString()))
                     && multiFormatSchema.getSchema() instanceof Schema openapiSchema) {
                 return findUnmarkedNestedSchemasForOpenAPISchema(markingContext, openapiSchema);
             }
@@ -240,7 +242,7 @@ private static Set<String> findUnmarkedNestedSchemas(
      * returns a Set of detected schema ids.
      *
      * @param markingContext the current {@link MarkingContext}
-     * @param schema the {@link SchemaObject} to analyze
+     * @param schema         the {@link SchemaObject} to analyze
      * @return Set of schema ids representing nested schema refs
      */
     private static Set<String> findUnmarkedNestedSchemasForAsyncAPISchema(
@@ -276,12 +278,17 @@ private static Set<String> findUnmarkedNestedSchemasForAsyncAPISchema(
      * returns a Set of detected schema ids.
      *
      * @param markingContext the current {@link MarkingContext}
-     * @param openapiSchema the Swagger {@link Schema} to analyze
+     * @param openapiSchema  the Swagger {@link Schema} to analyze
      * @return Set of schema ids representing nested schema refs
      */
     private static Set<String> findUnmarkedNestedSchemasForOpenAPISchema(
             MarkingContext markingContext, Schema<?> openapiSchema) {
-        Stream<Schema> propertySchemas = openapiSchema.getProperties().values().stream();
+        final Stream<Schema> propertySchemas;
+        if (openapiSchema.getProperties() != null) {
+            propertySchemas = openapiSchema.getProperties().values().stream();
+        } else {
+            propertySchemas = Stream.empty();
+        }
 
         Stream<Schema> referencedSchemas = Stream.of(
                         openapiSchema.getAllOf(), openapiSchema.getAnyOf(), openapiSchema.getOneOf())

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/scanners/common/headers/HeaderClassExtractor.java

@@ -34,7 +34,8 @@ public SchemaObject extractHeader(Method method, PayloadSchemaObject payload) {
                 Header headerAnnotation = argument.getAnnotation(Header.class);
                 String headerName = getHeaderAnnotationName(headerAnnotation);
 
-                SwaggerSchemaService.ExtractedSchemas extractedSchema = schemaService.extractSchema(argument.getType());
+                SwaggerSchemaService.ExtractedSchemas extractedSchema =
+                        schemaService.postProcessSimpleSchema(argument.getType());
                 ComponentSchema rootComponentSchema = extractedSchema.rootSchema();
 
                 // to stay compatible with former versions.

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/scanners/common/message/AsyncAnnotationMessageService.java

@@ -42,8 +42,8 @@ public MessageObject buildMessage(AsyncOperation operationData, Method method) {
         Map<String, MessageBinding> messageBinding =
                 AsyncAnnotationUtil.processMessageBindingFromAnnotation(method, messageBindingProcessors);
 
-        var messagePayload = MessagePayload.of(
-                MultiFormatSchema.builder().schema(payloadSchema.payload()).build());
+        MultiFormatSchema multiFormatSchema = MultiFormatSchema.of(payloadSchema.payload());
+        MessagePayload messagePayload = MessagePayload.of(multiFormatSchema);
 
         var builder = MessageObject.builder()
                 .messageId(payloadSchema.name())

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/scanners/common/payload/internal/PayloadService.java

@@ -36,6 +36,14 @@ public PayloadSchemaObject buildSchema(Type payloadType) {
         return buildSchema(contentType, payloadType);
     }
 
+    /**
+     * creates a {@link PayloadSchemaObject} from the given type and content type. Registers the created schema objects
+     * with this {@link ComponentsService}.
+     *
+     * @param contentType
+     * @param payloadType
+     * @return
+     */
     public PayloadSchemaObject buildSchema(String contentType, Type payloadType) {
         String schemaName = componentsService.getSchemaName(payloadType);
         String simpleSchemaName = componentsService.getSimpleSchemaName(payloadType);

springwolf-core/src/main/java/io/github/springwolf/core/asyncapi/schemas/ModelConvertersProvider.java

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.github.springwolf.core.asyncapi.schemas;
+
+import io.github.springwolf.asyncapi.v3.model.schema.SchemaFormat;
+import io.github.springwolf.core.configuration.properties.PayloadSchemaFormat;
+import io.swagger.v3.core.converter.ModelConverter;
+import io.swagger.v3.core.converter.ModelConverters;
+
+import java.util.List;
+
+/**
+ * Provides fully prepared {@link io.swagger.v3.core.converter.ModelConverters} for openapi v3 and v3.1
+ * requirements.
+ */
+public class ModelConvertersProvider {
+
+    private final ModelConverters converter_openapi30;
+    private final ModelConverters converter_openapi31;
+
+    public ModelConvertersProvider(List<ModelConverter> externalModelConverters) {
+        converter_openapi30 = new ModelConverters(false);
+        converter_openapi31 = new ModelConverters(true);
+        externalModelConverters.forEach(converter_openapi30::addConverter);
+        externalModelConverters.forEach(converter_openapi31::addConverter);
+    }
+
+    /**
+     * provides the appropriate {@link ModelConverters} for the given {@link SchemaFormat}.
+     *
+     * @param schemaFormat the schemaFormat that shall be generated.
+     * @return the appropriate {@link ModelConverters} or {@link IllegalArgumentException} if the given format is not supported.
+     */
+    public ModelConverters getModelConverterFor(PayloadSchemaFormat schemaFormat) {
+        return switch (schemaFormat) {
+            case ASYNCAPI_V3, OPENAPI_V3 -> converter_openapi30;
+            case OPENAPI_V3_1 -> converter_openapi31;
+        };
+    }
+}