feat: schemaformat option for payload schemas added

Author: tvahrst

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

@@ -7,6 +7,7 @@
 import com.networknt.schema.JsonSchemaFactory;
 import com.networknt.schema.SpecVersionDetector;
 import io.github.springwolf.asyncapi.v3.model.components.ComponentSchema;
+import io.github.springwolf.asyncapi.v3.model.schema.SchemaFormat;
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaObject;
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaReference;
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaType;
@@ -42,7 +43,7 @@ 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(), SchemaFormat.ASYNCAPI_V3);
 
         // when
         verifyValidJsonSchema(expectedJsonSchema);
@@ -67,7 +68,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/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,7 +34,7 @@ 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);
@@ -43,7 +44,7 @@ public interface ComponentsService {
      * @param headers the schema to register, typically a header schema
      * @return the title attribute of the given schema
      */
-    String registerSchema(SchemaObject headers);
+    String registerSimpleSchema(SchemaObject headers);
 
     /**
      * Provides a map of all registered messages.

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

@@ -5,10 +5,11 @@
 import io.github.springwolf.asyncapi.v3.model.channel.message.MessageObject;
 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.SchemaFormat;
 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;
 
 import java.lang.reflect.Type;
@@ -22,11 +23,10 @@
  * in the resulting AsyncApi object.
  */
 @Slf4j
-@AllArgsConstructor
 public class DefaultComponentsService implements ComponentsService {
 
     private final SwaggerSchemaService schemaService;
-    private final SpringwolfConfigProperties springwolfConfigProperties;
+    private final SchemaFormat payloadSchemaFormat;
 
     /**
      * maps a schema name (key) to a detected corresponding {@link ComponentSchema}.
@@ -35,6 +35,15 @@ public class DefaultComponentsService implements ComponentsService {
 
     private final Map<String, Message> messages = new HashMap<>();
 
+    public DefaultComponentsService(
+            SwaggerSchemaService schemaService, SpringwolfConfigProperties springwolfConfigProperties) {
+        this.schemaService = schemaService;
+
+        PayloadSchemaFormat payloadSchemaFormat =
+                springwolfConfigProperties.getDocket().getPayloadSchemaFormat();
+        this.payloadSchemaFormat = payloadSchemaFormat.getSchemaFormat();
+    }
+
     /**
      * Provides a map of all registered schemas.
      *
@@ -51,12 +60,13 @@ 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);
+        SwaggerSchemaService.ExtractedSchemas payload =
+                schemaService.resolveSchema(type, contentType, payloadSchemaFormat);
         payload.referencedSchemas().forEach(schemas::putIfAbsent);
         return payload.rootSchema();
     }
@@ -67,17 +77,17 @@ public ComponentSchema resolvePayloadSchema(Type type, String contentType) {
      * Use only with schemas with max. one level of properties. Providing {@link SchemaObject}s with deep
      * property hierarchy will result in an 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
      * @return the title attribute of the given schema
      */
     @Override
-    public String registerSchema(SchemaObject headers) {
+    public String registerSimpleSchema(SchemaObject headers) {
         log.debug("Registering schema for {}", headers.getTitle());
 
-        SchemaObject headerSchema = schemaService.extractSchema(headers);
-        this.schemas.putIfAbsent(headers.getTitle(), ComponentSchema.of(headerSchema));
+        ComponentSchema processedSchema = schemaService.postProcessSimpleSchema(headers);
+        this.schemas.putIfAbsent(headers.getTitle(), processedSchema);
 
         return headers.getTitle();
     }

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

@@ -37,7 +37,7 @@ public MessageObject buildMessage(AsyncOperation operationData, Method method) {
         PayloadSchemaObject payloadSchema = payloadAsyncOperationService.extractSchema(operationData, method);
 
         SchemaObject headerSchema = AsyncAnnotationUtil.getAsyncHeaders(operationData, stringValueResolver);
-        String headerSchemaName = this.componentsService.registerSchema(headerSchema);
+        String headerSchemaName = this.componentsService.registerSimpleSchema(headerSchema);
 
         Map<String, MessageBinding> messageBinding =
                 AsyncAnnotationUtil.processMessageBindingFromAnnotation(method, messageBindingProcessors);

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

@@ -31,7 +31,7 @@ public MessageObject buildMessage(
             MethodAnnotation annotation, PayloadSchemaObject payloadSchema, SchemaObject headers) {
         SchemaObject headerSchema = asyncHeadersBuilder.buildHeaders(payloadSchema);
         SchemaObject mergedHeaderSchema = HeaderSchemaObjectMerger.merge(headerSchema, headers);
-        String headerModelName = componentsService.registerSchema(mergedHeaderSchema);
+        String headerModelName = componentsService.registerSimpleSchema(mergedHeaderSchema);
 
         Map<String, MessageBinding> messageBinding = bindingFactory.buildMessageBinding(annotation, mergedHeaderSchema);
 

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

@@ -62,7 +62,7 @@ private MessageObject buildMessage(ClassAnnotation classAnnotation, Method metho
         SchemaObject headerSchema = asyncHeadersBuilder.buildHeaders(payloadSchema);
         SchemaObject headers = headerClassExtractor.extractHeader(method, payloadSchema);
         SchemaObject mergedHeaderSchema = HeaderSchemaObjectMerger.merge(headerSchema, headers);
-        String headerSchemaName = componentsService.registerSchema(mergedHeaderSchema);
+        String headerSchemaName = componentsService.registerSimpleSchema(mergedHeaderSchema);
 
         Map<String, MessageBinding> messageBinding = bindingFactory.buildMessageBinding(classAnnotation, headerSchema);
 

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);
@@ -47,7 +55,7 @@ public PayloadSchemaObject buildSchema(String contentType, Type payloadType) {
     public PayloadSchemaObject useUnusedPayload() {
         ComponentSchema schema = PAYLOAD_NOT_USED.schema();
         if (schema != null && schema.getSchema() != null) {
-            this.componentsService.registerSchema(schema.getSchema());
+            this.componentsService.registerSimpleSchema(schema.getSchema());
         }
         return PAYLOAD_NOT_USED;
     }

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

@@ -4,6 +4,7 @@
 import com.fasterxml.jackson.databind.JavaType;
 import io.github.springwolf.asyncapi.v3.model.ReferenceUtil;
 import io.github.springwolf.asyncapi.v3.model.components.ComponentSchema;
+import io.github.springwolf.asyncapi.v3.model.schema.SchemaFormat;
 import io.github.springwolf.asyncapi.v3.model.schema.SchemaObject;
 import io.github.springwolf.core.asyncapi.annotations.AsyncApiPayload;
 import io.github.springwolf.core.asyncapi.components.postprocessors.SchemasPostProcessor;
@@ -35,7 +36,9 @@
 
 @Slf4j
 public class SwaggerSchemaService {
-    private final ModelConverters converter = ModelConverters.getInstance();
+    private final ModelConverters converter_openapi30 = ModelConverters.getInstance(false);
+    private final ModelConverters converter_openapi31 = ModelConverters.getInstance(true);
+
     private final List<SchemasPostProcessor> schemaPostProcessors;
     private final SwaggerSchemaUtil swaggerSchemaUtil;
     private final SpringwolfConfigProperties properties;
@@ -46,7 +49,8 @@ public SwaggerSchemaService(
             SwaggerSchemaUtil swaggerSchemaUtil,
             SpringwolfConfigProperties properties) {
 
-        externalModelConverters.forEach(converter::addConverter);
+        externalModelConverters.forEach(converter_openapi30::addConverter);
+        externalModelConverters.forEach(converter_openapi31::addConverter);
         this.schemaPostProcessors = schemaPostProcessors;
         this.swaggerSchemaUtil = swaggerSchemaUtil;
         this.properties = properties;
@@ -68,7 +72,7 @@ public record ExtractedSchemas(ComponentSchema rootSchema, Map<String, Component
      * @param headers
      * @return
      */
-    public SchemaObject extractSchema(SchemaObject headers) {
+    public ComponentSchema postProcessSimpleSchema(SchemaObject headers) {
         String schemaName = headers.getTitle();
 
         // create a swagger schema to invoke the postprocessors. Copy attributes vom headers to (Swagger) headerSchema
@@ -91,24 +95,44 @@ public SchemaObject extractSchema(SchemaObject headers) {
         postProcessSchemas(newSchemasToProcess, new HashMap<>(newSchemasToProcess), DEFAULT_CONTENT_TYPE);
 
         // convert Swagger schema back to an AsnycApi SchemaObject
-        return swaggerSchemaUtil.mapSchema(headerSchema);
+        return swaggerSchemaUtil.mapSchema(headerSchema, SchemaFormat.ASYNCAPI_V3);
     }
 
-    public ExtractedSchemas extractSchema(Class<?> type) {
-        return this.resolveSchema(type, "");
+    public ExtractedSchemas postProcessSimpleSchema(Class<?> type) {
+        return this.resolveSchema(type, "", SchemaFormat.ASYNCAPI_V3);
     }
 
-    public ExtractedSchemas resolveSchema(Type type, String contentType) {
+    /**
+     * creates a {@link ExtractedSchemas} from the given type. The resulting ExtractedSchemas will contain the root
+     * schema (which is always a schema ref) and a List of conrecte schemas referenced from the root schema.
+     *
+     * @param type
+     * @param contentType
+     * @param schemaFormat SchemaFormat to use
+     * @return
+     */
+    public ExtractedSchemas resolveSchema(Type type, String contentType, SchemaFormat schemaFormat) {
         String actualContentType =
                 StringUtils.isBlank(contentType) ? properties.getDocket().getDefaultContentType() : contentType;
+
+        // use swagger to resolve type to a swagger ResolvedSchema Object.
+        ModelConverters converterToUse =
+                switch (schemaFormat) {
+                    case ASYNCAPI_V3 -> converter_openapi30;
+                    case OPENAPI_V3 -> converter_openapi30;
+                    case OPENAPI_V3_1 -> converter_openapi31;
+                    default -> throw new IllegalArgumentException("SchemaFormat not supported: " + schemaFormat);
+                };
+
         ResolvedSchema resolvedSchema = runWithFqnSetting(
-                (unused) -> converter.resolveAsResolvedSchema(new AnnotatedType(type).resolveAsRef(true)));
+                (unused) -> converterToUse.resolveAsResolvedSchema(new AnnotatedType(type).resolveAsRef(true)));
 
         if (resolvedSchema == null) {
             // defaulting to stringSchema when resolvedSchema is null
-            SchemaObject payloadSchema = swaggerSchemaUtil.mapSchema(
-                    PrimitiveType.fromType(String.class).createProperty());
-            return new ExtractedSchemas(ComponentSchema.of(payloadSchema), Map.of());
+            Schema<?> stringPropertySchema =
+                    PrimitiveType.fromType(String.class).createProperty();
+            ComponentSchema stringComponentSchema = swaggerSchemaUtil.mapSchema(stringPropertySchema, schemaFormat);
+            return new ExtractedSchemas(stringComponentSchema, Map.of());
         } else {
             Map<String, Schema> newSchemasToProcess = new LinkedHashMap<>(resolvedSchema.referencedSchemas);
             newSchemasToProcess.putIfAbsent(getNameFromType(type), resolvedSchema.schema);
@@ -117,7 +141,7 @@ public ExtractedSchemas resolveSchema(Type type, String contentType) {
             HashMap<String, Schema> processedSchemas = new HashMap<>(newSchemasToProcess);
             postProcessSchemas(newSchemasToProcess, processedSchemas, actualContentType);
 
-            return createExtractedSchemas(resolvedSchema.schema, processedSchemas);
+            return createExtractedSchemas(resolvedSchema.schema, processedSchemas, schemaFormat);
         }
     }
 
@@ -126,15 +150,14 @@ public ExtractedSchemas resolveSchema(Type type, String contentType) {
      *
      * @param rootSchema        Swagger root schema
      * @param referencedSchemas all referenced swagger schemas
+     * @param schemaFormat      the schema-format of the schemas inside the resulting ExtractedSchemas
      * @return
      */
-    private ExtractedSchemas createExtractedSchemas(Schema rootSchema, Map<String, Schema> referencedSchemas) {
-        ComponentSchema rootComponentSchema = swaggerSchemaUtil.mapSchemaOrRef(rootSchema);
-        Map<String, SchemaObject> referencedSchemaObjects = swaggerSchemaUtil.mapSchemasMap(referencedSchemas);
-        Map<String, ComponentSchema> referencedComponentSchemas = new HashMap<>();
-        referencedSchemaObjects.forEach((schemaname, schemaobject) -> {
-            referencedComponentSchemas.put(schemaname, ComponentSchema.of(schemaobject));
-        });
+    private ExtractedSchemas createExtractedSchemas(
+            Schema rootSchema, Map<String, Schema> referencedSchemas, SchemaFormat schemaFormat) {
+        ComponentSchema rootComponentSchema = swaggerSchemaUtil.mapSchemaOrRef(rootSchema, schemaFormat);
+        Map<String, ComponentSchema> referencedComponentSchemas =
+                swaggerSchemaUtil.mapSchemasMap(referencedSchemas, schemaFormat);
 
         return new ExtractedSchemas(rootComponentSchema, referencedComponentSchemas);
     }