Merge pull request #17 from framefork/fp-openapi-schema

add Support for openapi Schema type definitions

Author: fprochazka

README.md

@@ -291,6 +291,17 @@ This also simplifies usage on every other place, where Hibernate might need to r
 
 This library provides `ObjectBigIntIdJacksonModule` and `ObjectUuidJacksonModule`, which can be registered automatically via the standard `java.util.ServiceLoader` mechanism, or explicitly.
 
+Please note that in Spring, the instance of Jackson's `ObjectMapper` used for (de)serializing requests and responses of controllers by default ignores the modules provided via `ServiceLoader`,
+so to make it work, you have to either register the modules as beans, or add the following customizer:
+
+```java
+@Bean
+public Jackson2ObjectMapperBuilderCustomizer enableServiceLoaderModules()
+{
+    return builder -> builder.findModulesViaServiceLoader(true);
+}
+```
+
 ## Usage: (de)serialization with Gson
 
 This library provides `ObjectBigIntIdTypeAdapterFactory` and `ObjectUuidTypeAdapterFactory`, which can be registered automatically via the standard `java.util.ServiceLoader` mechanism, or explicitly.
@@ -336,6 +347,34 @@ and then mark the type as `@Contextual` on every usage
 data class UserDto(@Contextual val id: UserId)
 ```
 
+## Usage: OpenAPI schema
+
+This library provides support for OpenAPI schema generation, so that you don't have to annotate the types with `@Schema` manually (you still can, if you want to).
+
+### OpenAPI - generic Swagger v3 Jakarta
+
+The [org.framefork:typed-ids-openapi-swagger-jakarta](https://central.sonatype.com/artifact/org.framefork/typed-ids-openapi-swagger-jakarta) artifact
+provides a `TypedIdsModelConverter`, which should be automatically picked up by the standard Swagger v3 Jakarta implementation,
+because it's exposed via the standard `java.util.ServiceLoader` mechanism.
+
+There is a single configurable property - `idsAsRef`, which is the equivalent of `enumsAsRef` in the standard Swagger v3 implementation.
+You can set override it via `TypedIdsModelConverter.idsAsRef`, or using a system property `framefork.typed-ids.openapi.as-ref`.
+
+Providing a non-jakarta variant would be straightforward, but given that javax has been deprecated for a long time, I decided to not bother with it.
+
+### OpenAPI - SpringDoc
+
+The [org.framefork:typed-ids-openapi-springdoc](https://central.sonatype.com/artifact/org.framefork/typed-ids-openapi-springdoc) artifact
+builds on the Swagger v3 Jakarta integration, and registers it as a standard Spring bean.
+
+With SpringDoc, you shouldn't configure the converter explicitly,
+and instead you should use the standard spring configuration to set it via the `framefork.typed-ids.openapi.as-ref` property in config/ENV/etc.
+
+You may notice that the artifact depends on a quite old version of the SpringDoc. That is because I needed compatibility with Spring Boot 3.0.x. However, it works seamlessly with newer Spring Boot versions.
+
+You may want to check the working example in [testing/testing-typed-ids-springdoc-openapi](https://github.com/framefork/typed-ids/tree/master/testing/testing-typed-ids-springdoc-openapi),
+with a recent Spring Boot version, and also with a working OpenApi spec generation, and TypeScript client generation.
+
 ## More examples
 
 To learn more you can explore the `testing/` directory of this library,

gradle/libs.versions.toml

@@ -38,3 +38,6 @@ hypersistence-utils-hibernate62 = { group = "io.hypersistence", name = "hypersis
 hypersistence-utils-hibernate63 = { group = "io.hypersistence", name = "hypersistence-utils-hibernate-63", version = "3.9.9" }
 hypersistence-tsid = { module = "io.hypersistence:hypersistence-tsid", version = "2.1.4" }
 kotlinx-serialization = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version = "1.7.0" }
+swagger-v3-core-jakarta = { module = "io.swagger.core.v3:swagger-core-jakarta", version = "2.2.35" }
+springdoc-openapi-starter-common = { module = "org.springdoc:springdoc-openapi-starter-common", version = "2.1.0" }
+springdoc-openapi-spring-configuration-processor = { module = "org.springframework.boot:spring-boot-configuration-processor", version = "3.0.5" }

modules/typed-ids-openapi-springdoc/build.gradle.kts

@@ -0,0 +1,20 @@
+plugins {
+    id("framefork.java-public")
+}
+
+dependencies {
+    api(project(":typed-ids"))
+    api(project(":typed-ids-openapi-swagger-jakarta"))
+    api(libs.springdoc.openapi.starter.common)
+
+    compileOnly(libs.jetbrains.annotations)
+
+    compileOnly(libs.autoService.annotations)
+    annotationProcessor(libs.autoService.processor)
+    annotationProcessor(libs.springdoc.openapi.spring.configuration.processor)
+
+    testImplementation(project(":typed-ids-testing"))
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+project.description = "TypeIds seamless integration with SpringDoc OpenAPI"

modules/typed-ids-openapi-springdoc/src/main/java/org/framefork/typedIds/springdoc/config/TypedIdsOpenApiAutoConfiguration.java

@@ -0,0 +1,27 @@
+package org.framefork.typedIds.springdoc.config;
+
+import org.framefork.typedIds.swagger.TypedIdsModelConverter;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+@AutoConfiguration
+@EnableConfigurationProperties(TypedIdsOpenApiProperties.class)
+public class TypedIdsOpenApiAutoConfiguration
+{
+
+    private final TypedIdsOpenApiProperties properties;
+
+    public TypedIdsOpenApiAutoConfiguration(final TypedIdsOpenApiProperties properties)
+    {
+        this.properties = properties;
+    }
+
+    @Bean
+    public TypedIdsModelConverter typedIdsModelConverter()
+    {
+        TypedIdsModelConverter.idsAsRef = this.properties.getAsRef();
+        return new TypedIdsModelConverter();
+    }
+
+}

modules/typed-ids-openapi-springdoc/src/main/java/org/framefork/typedIds/springdoc/config/TypedIdsOpenApiProperties.java

@@ -0,0 +1,25 @@
+package org.framefork.typedIds.springdoc.config;
+
+import jakarta.validation.constraints.NotNull;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties(prefix = TypedIdsOpenApiProperties.PREFIX)
+public class TypedIdsOpenApiProperties
+{
+
+    public static final String PREFIX = "framefork.typed-ids.openapi";
+
+    @NotNull
+    private Boolean asRef = true;
+
+    public Boolean getAsRef()
+    {
+        return asRef;
+    }
+
+    public void setAsRef(final Boolean asRef)
+    {
+        this.asRef = asRef;
+    }
+
+}

modules/typed-ids-openapi-springdoc/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1 @@
+org.framefork.typedIds.springdoc.config.TypedIdsOpenApiAutoConfiguration

modules/typed-ids-openapi-swagger-jakarta/build.gradle.kts

@@ -0,0 +1,18 @@
+plugins {
+    id("framefork.java-public")
+}
+
+dependencies {
+    api(project(":typed-ids"))
+    api(libs.swagger.v3.core.jakarta)
+
+    compileOnly(libs.jetbrains.annotations)
+
+    compileOnly(libs.autoService.annotations)
+    annotationProcessor(libs.autoService.processor)
+
+    testImplementation(project(":typed-ids-testing"))
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+project.description = "TypeIds seamless integration with swagger-core-jakarta, and any systems that use it"

modules/typed-ids-openapi-swagger-jakarta/src/main/java/org/framefork/typedIds/swagger/TypedIdsModelConverter.java

@@ -0,0 +1,52 @@
+package org.framefork.typedIds.swagger;
+
+import com.google.auto.service.AutoService;
+import io.swagger.v3.core.converter.AnnotatedType;
+import io.swagger.v3.core.converter.ModelConverter;
+import io.swagger.v3.core.converter.ModelConverterContext;
+import io.swagger.v3.core.jackson.ModelResolver;
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.media.Schema;
+import org.framefork.typedIds.TypedId;
+import org.jspecify.annotations.Nullable;
+
+import java.util.Iterator;
+import java.util.Objects;
+
+@AutoService(ModelConverter.class)
+public class TypedIdsModelConverter implements ModelConverter
+{
+
+    public static final String IDS_AS_REFS_PROPERTY_NAME = "framefork.typed-ids.openapi.as-ref";
+
+    /**
+     * Allows all VO-IDs to be resolved as a reference to a scheme added to the components section.
+     * <p/>
+     * This is not a very good way to configure something, but it is consistent with {@link ModelResolver#enumsAsRef}
+     */
+    @SuppressWarnings("NonFinalStaticField")
+    public static boolean idsAsRef = Objects.equals(System.getProperty(IDS_AS_REFS_PROPERTY_NAME, "true"), "true");
+
+    @SuppressWarnings("rawtypes")
+    @Nullable
+    @Override
+    public Schema resolve(final AnnotatedType type, final ModelConverterContext context, final Iterator<ModelConverter> chain)
+    {
+        final Class<?> rawClass = TypedIdsSchemaUtils.rawClassOf(type.getType());
+        if (rawClass != null && TypedId.class.isAssignableFrom(rawClass)) {
+            var schema = TypedIdsSchemaUtils.createSchema(rawClass);
+
+            if (idsAsRef) {
+                var schemaRef = new Schema().$ref(Components.COMPONENTS_SCHEMAS_REF + schema.getName());
+                context.defineModel(schema.getName(), schema, rawClass, null);
+                return schemaRef;
+
+            } else {
+                return schema.name(null);
+            }
+        }
+
+        return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
+    }
+
+}

modules/typed-ids-openapi-swagger-jakarta/src/main/java/org/framefork/typedIds/swagger/TypedIdsSchemaUtils.java

@@ -0,0 +1,151 @@
+package org.framefork.typedIds.swagger;
+
+import com.fasterxml.jackson.databind.type.SimpleType;
+import io.swagger.v3.core.converter.AnnotatedType;
+import io.swagger.v3.core.converter.ModelConverterContext;
+import io.swagger.v3.core.converter.ModelConverterContextImpl;
+import io.swagger.v3.core.converter.ModelConverters;
+import io.swagger.v3.oas.models.media.IntegerSchema;
+import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.media.StringSchema;
+import org.framefork.typedIds.TypedId;
+import org.framefork.typedIds.bigint.ObjectBigIntId;
+import org.framefork.typedIds.uuid.ObjectUuid;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.Nullable;
+
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Predicate;
+
+@SuppressWarnings("rawtypes")
+@ApiStatus.Internal
+public final class TypedIdsSchemaUtils
+{
+
+    public static final int UUID_LENGTH = 36;
+
+    private final static ConcurrentHashMap<Class<?>, Schema> DEFAULT_SCHEMAS = new ConcurrentHashMap<>();
+
+    private TypedIdsSchemaUtils()
+    {
+    }
+
+    public static Schema createSchema(final Class<?> rawClass)
+    {
+        if (ObjectUuid.class.isAssignableFrom(rawClass)) {
+            return createUuidSchema(rawClass);
+
+        } else if (ObjectBigIntId.class.isAssignableFrom(rawClass)) {
+            return createBigIntSchema(rawClass);
+        }
+
+        throw new IllegalArgumentException("Given class is not a subtype of %s, %s was given".formatted(TypedId.class, rawClass));
+    }
+
+    public static Schema createUuidSchema(final Class<?> rawClass)
+    {
+        // Map UUID-based typed IDs to primitive string:uuid in OpenAPI
+        var result = new StringSchema()
+            .format("uuid")
+            .minLength(UUID_LENGTH)
+            .maxLength(UUID_LENGTH);
+
+        return applyDefaultSchema(result, getDefaultSchema(rawClass));
+    }
+
+    public static Schema createBigIntSchema(final Class<?> rawClass)
+    {
+        // Map bigint-based typed IDs to primitive integer:int64 in OpenAPI
+        var result = new IntegerSchema()
+            .format("int64");
+
+        return applyDefaultSchema(result, getDefaultSchema(rawClass));
+    }
+
+    private static Schema applyDefaultSchema(final Schema result, final Schema defaultSchema)
+    {
+        Optional.ofNullable(defaultSchema.getName())
+            .filter(Predicate.not(String::isBlank))
+            .ifPresent(result::setName);
+        Optional.ofNullable(defaultSchema.getDescription())
+            .filter(Predicate.not(String::isBlank))
+            .ifPresent(result::setDescription);
+        return result;
+    }
+
+    public static Schema getDefaultSchema(final Class<?> rawClass)
+    {
+        return DEFAULT_SCHEMAS.computeIfAbsent(rawClass, TypedIdsSchemaUtils::computeDefaultSchema);
+    }
+
+    private static Schema computeDefaultSchema(final Class<?> rawClass)
+    {
+        var converterContext = getModelConverterContext();
+        var schema = converterContext.resolve(
+            new AnnotatedType()
+                .type(rawClass)
+                .resolveAsRef(false)
+        );
+
+        var schemaAnnotation = rawClass.getDeclaredAnnotation(io.swagger.v3.oas.annotations.media.Schema.class);
+        var declaredName = Optional.ofNullable(schemaAnnotation).map(io.swagger.v3.oas.annotations.media.Schema::name).filter(Predicate.not(String::isBlank)).isPresent();
+        if (!declaredName) {
+            schema.setName(getAutomaticSchemaNameForClass(rawClass));
+
+        } else {
+            if (schema.getName() == null || schema.getName().isBlank()) {
+                schema.setName(getAutomaticSchemaNameForClass(rawClass));
+            }
+        }
+
+        if (schema.getDescription() == null || schema.getDescription().isBlank()) {
+            schema.setDescription("ID of type " + schema.getName());
+        }
+
+        return schema;
+    }
+
+    @Nullable
+    public static Class<?> rawClassOf(final Type type)
+    {
+        if (type instanceof SimpleType simpleType) {
+            return simpleType.getRawClass();
+        }
+        if (type instanceof Class<?> c) {
+            return c;
+        }
+        if (type instanceof ParameterizedType p) {
+            final Type raw = p.getRawType();
+            if (raw instanceof Class<?> c) {
+                return c;
+            }
+        }
+        return null;
+    }
+
+    private static ModelConverterContext getModelConverterContext()
+    {
+        var converters = ModelConverters.getInstance().getConverters().stream()
+            .filter(converter -> !(converter instanceof TypedIdsModelConverter))
+            .toList();
+        return new ModelConverterContextImpl(converters);
+    }
+
+    /**
+     * this automatically fixes names of `User.Id` which would otherwise become `Id` but we want it to be `UserId`
+     */
+    private static String getAutomaticSchemaNameForClass(final Class<?> clazz)
+    {
+        final Class<?> enclosing = clazz.getEnclosingClass();
+        if (enclosing == null) {
+            return clazz.getSimpleName();
+        }
+        final String outer = getAutomaticSchemaNameForClass(enclosing);
+        final String inner = clazz.getSimpleName();
+        return outer + "_" + inner;
+    }
+
+}