feat: add OpenAPI generation infrastructure

Add reusable components for automated OpenAPI spec generation:
- @EnableOpenApiGen meta-annotation combining all required auto-configs
- AutoMockMissingBeansConfig for mocking controller dependencies at build time
- application-openapi-gen.yaml profile config
- mockito-core as optional compile dependency

Author: casc84ab

README.md

@@ -110,9 +110,53 @@ firefly:
       log-body: false
 ```
 
-## Documentation
+## OpenAPI Generation Infrastructure
+
+This module provides the reusable infrastructure for automated OpenAPI spec generation and SDK creation at build time. Microservices use these components to generate an OpenAPI spec from their controller annotations without loading any production dependencies.
+
+### Components
+
+| Component | Purpose |
+|-----------|---------|
+| `@EnableOpenApiGen` | Meta-annotation that combines `@SpringBootConfiguration`, `@EnableWebFlux`, and all required auto-configurations (Springdoc, WebFlux, Jackson) into a single annotation |
+| `AutoMockMissingBeansConfig` | `BeanDefinitionRegistryPostProcessor` that automatically creates Mockito mocks for any `@Autowired` dependency not present in the context. Only active under the `openapi-gen` Spring profile |
+| `application-openapi-gen.yaml` | Profile-specific config that enables Springdoc and allows bean definition overriding. Auto-discovered from the classpath by Spring Boot |
+
+### How It Works
 
-No additional documentation available for this project.
+1. A lightweight Spring Boot app (`OpenApiGenApplication`) starts during the Maven build using the test classpath
+2. `@EnableOpenApiGen` imports the minimal set of auto-configurations needed for Springdoc + WebFlux
+3. `AutoMockMissingBeansConfig` scans all `@RestController` beans and registers Mockito mocks for their `@Autowired` dependencies — this allows controllers to load without their real service implementations
+4. Springdoc reads the controller annotations and exposes the OpenAPI spec at `/v3/api-docs.yaml`
+5. The `springdoc-openapi-maven-plugin` fetches the spec and writes it to `target/openapi/openapi.yml`
+6. The SDK module uses `openapi-generator-maven-plugin` to generate typed API clients from the spec
+
+### Usage in a Microservice
+
+**1. Create `OpenApiGenApplication` in `src/test/java`:**
+
+```java
+@EnableOpenApiGen
+@ComponentScan(basePackages = "com.firefly.your.module.web.controllers")
+public class OpenApiGenApplication {
+    public static void main(String[] args) {
+        SpringApplication.run(OpenApiGenApplication.class, args);
+    }
+}
+```
+
+**2. Add properties to the `-web` module's `pom.xml`:**
+
+```xml
+<properties>
+    <openapi.gen.skip>false</openapi.gen.skip>
+    <openapi.gen.mainClass>com.firefly.your.module.web.openapi.OpenApiGenApplication</openapi.gen.mainClass>
+</properties>
+```
+
+The Maven profile and plugin configuration are inherited from `firefly-parent`. See the [firefly-parent README](https://github.com/firefly-oss/firefly-parent) for details.
+
+## Documentation
 
 ## Contributing
 

pom.xml

@@ -43,6 +43,13 @@
             <artifactId>swagger-annotations</artifactId>
         </dependency>
 
+        <!-- Mockito (optional — only needed at compile time for AutoMockMissingBeansConfig) -->
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <optional>true</optional>
+        </dependency>
+
         <!-- Utils -->
         <dependency>
             <groupId>org.projectlombok</groupId>

src/main/java/org/fireflyframework/web/openapi/AutoMockMissingBeansConfig.java

@@ -0,0 +1,130 @@
+/*
+ * Copyright 2024-2026 Firefly Software Solutions Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.fireflyframework.web.openapi;
+
+import org.mockito.Mockito;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.beans.factory.support.BeanDefinitionRegistryPostProcessor;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Profile;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.lang.reflect.Field;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Automatically registers Mockito mock beans for every {@code @Autowired}
+ * dependency of {@code @RestController} classes that is not already present
+ * in the bean registry.
+ *
+ * <p>Mocks are registered as pre-existing singletons via
+ * {@link ConfigurableListableBeanFactory#registerSingleton} so that Spring
+ * does not attempt to process {@code @Autowired} annotations on the mock
+ * objects themselves (which would fail for concrete service classes that
+ * have their own unsatisfied dependencies).
+ *
+ * <p>Activated only under the {@code openapi-gen} Spring profile.
+ */
+@Configuration
+@Profile("openapi-gen")
+public class AutoMockMissingBeansConfig implements BeanDefinitionRegistryPostProcessor {
+
+    private static final Logger logger = LoggerFactory.getLogger(AutoMockMissingBeansConfig.class);
+
+    private final Map<String, Class<?>> mocksToRegister = new LinkedHashMap<>();
+
+    @Override
+    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {
+        for (String beanName : registry.getBeanDefinitionNames()) {
+            BeanDefinition bd = registry.getBeanDefinition(beanName);
+            String beanClassName = bd.getBeanClassName();
+            if (beanClassName == null) {
+                continue;
+            }
+
+            Class<?> beanClass;
+            try {
+                beanClass = Class.forName(beanClassName);
+            } catch (ClassNotFoundException e) {
+                continue;
+            }
+
+            if (!beanClass.isAnnotationPresent(RestController.class)) {
+                continue;
+            }
+
+            for (Field field : beanClass.getDeclaredFields()) {
+                if (!field.isAnnotationPresent(Autowired.class)) {
+                    continue;
+                }
+
+                Class<?> fieldType = field.getType();
+                String mockBeanName = "mock_" + fieldType.getSimpleName();
+
+                if (mocksToRegister.containsKey(fieldType.getName())) {
+                    continue;
+                }
+
+                if (isBeanTypeRegistered(registry, fieldType)) {
+                    continue;
+                }
+
+                logger.info("Will register Mockito mock for missing bean: {} (type: {})",
+                        mockBeanName, fieldType.getName());
+                mocksToRegister.put(fieldType.getName(), fieldType);
+            }
+        }
+    }
+
+    @Override
+    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
+        for (Map.Entry<String, Class<?>> entry : mocksToRegister.entrySet()) {
+            Class<?> fieldType = entry.getValue();
+            String mockBeanName = "mock_" + fieldType.getSimpleName();
+
+            logger.info("Registering Mockito mock singleton: {} (type: {})",
+                    mockBeanName, fieldType.getName());
+            beanFactory.registerSingleton(mockBeanName, Mockito.mock(fieldType));
+        }
+    }
+
+    private boolean isBeanTypeRegistered(BeanDefinitionRegistry registry, Class<?> type) {
+        for (String name : registry.getBeanDefinitionNames()) {
+            BeanDefinition bd = registry.getBeanDefinition(name);
+            String className = bd.getBeanClassName();
+            if (className == null) {
+                continue;
+            }
+            try {
+                Class<?> clazz = Class.forName(className);
+                if (type.isAssignableFrom(clazz)) {
+                    return true;
+                }
+            } catch (ClassNotFoundException e) {
+                // Skip
+            }
+        }
+        return false;
+    }
+}

src/main/java/org/fireflyframework/web/openapi/EnableOpenApiGen.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2024-2026 Firefly Software Solutions Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.fireflyframework.web.openapi;
+
+import org.springdoc.core.configuration.SpringDocConfiguration;
+import org.springdoc.core.properties.SpringDocConfigProperties;
+import org.springdoc.webflux.core.configuration.SpringDocWebFluxConfiguration;
+import org.springframework.boot.SpringBootConfiguration;
+import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
+import org.springframework.boot.autoconfigure.admin.SpringApplicationAdminJmxAutoConfiguration;
+import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;
+import org.springframework.boot.autoconfigure.web.reactive.HttpHandlerAutoConfiguration;
+import org.springframework.boot.autoconfigure.web.reactive.ReactiveWebServerFactoryAutoConfiguration;
+import org.springframework.boot.autoconfigure.web.reactive.WebFluxAutoConfiguration;
+import org.springframework.web.reactive.config.EnableWebFlux;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Meta-annotation that configures a minimal Spring Boot application for
+ * OpenAPI spec generation. Combines {@code @SpringBootConfiguration},
+ * {@code @EnableWebFlux}, and all required auto-configurations for Springdoc
+ * and WebFlux into a single annotation.
+ *
+ * <p>Usage in each microservice's {@code src/test/java}:
+ * <pre>{@code
+ * @EnableOpenApiGen
+ * @ComponentScan(basePackages = "com.example.web.controllers")
+ * public class OpenApiGenApplication {
+ *     public static void main(String[] args) {
+ *         SpringApplication.run(OpenApiGenApplication.class, args);
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p>The annotated class only needs to add {@code @ComponentScan} pointing at
+ * its controller package — everything else is handled by this annotation.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+@SpringBootConfiguration
+@EnableWebFlux
+@ImportAutoConfiguration({
+        AutoMockMissingBeansConfig.class,
+        SpringDocConfiguration.class,
+        SpringDocConfigProperties.class,
+        SpringDocWebFluxConfiguration.class,
+        ReactiveWebServerFactoryAutoConfiguration.class,
+        HttpHandlerAutoConfiguration.class,
+        WebFluxAutoConfiguration.class,
+        JacksonAutoConfiguration.class,
+        SpringApplicationAdminJmxAutoConfiguration.class
+})
+public @interface EnableOpenApiGen {
+}

src/main/resources/application-openapi-gen.yaml

@@ -0,0 +1,7 @@
+spring:
+  main:
+    allow-bean-definition-overriding: true
+springdoc:
+  api-docs:
+    enabled: true
+    version: openapi_3_0