Skip to content

Commit 8dd9372

Browse files
anconguiancongui
committed
Merge branch 'develop'
2 parents 5c1eec7 + b8e3e6a commit 8dd9372

5 files changed

Lines changed: 275 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ The idempotency subsystem provides a cache-backed idempotency filter that preven
5757
<dependency>
5858
<groupId>org.fireflyframework</groupId>
5959
<artifactId>fireflyframework-web</artifactId>
60-
<version>26.02.06</version>
60+
<version>26.02.07</version>
6161
</dependency>
6262
```
6363

@@ -110,9 +110,53 @@ firefly:
110110
log-body: false
111111
```
112112
113-
## Documentation
113+
## OpenAPI Generation Infrastructure
114+
115+
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.
116+
117+
### Components
118+
119+
| Component | Purpose |
120+
|-----------|---------|
121+
| `@EnableOpenApiGen` | Meta-annotation that combines `@SpringBootConfiguration`, `@EnableWebFlux`, and all required auto-configurations (Springdoc, WebFlux, Jackson) into a single annotation |
122+
| `AutoMockMissingBeansConfig` | `BeanDefinitionRegistryPostProcessor` that automatically creates Mockito mocks for any `@Autowired` dependency not present in the context. Only active under the `openapi-gen` Spring profile |
123+
| `application-openapi-gen.yaml` | Profile-specific config that enables Springdoc and allows bean definition overriding. Auto-discovered from the classpath by Spring Boot |
124+
125+
### How It Works
114126

115-
No additional documentation available for this project.
127+
1. A lightweight Spring Boot app (`OpenApiGenApplication`) starts during the Maven build using the test classpath
128+
2. `@EnableOpenApiGen` imports the minimal set of auto-configurations needed for Springdoc + WebFlux
129+
3. `AutoMockMissingBeansConfig` scans all `@RestController` beans and registers Mockito mocks for their `@Autowired` dependencies — this allows controllers to load without their real service implementations
130+
4. Springdoc reads the controller annotations and exposes the OpenAPI spec at `/v3/api-docs.yaml`
131+
5. The `springdoc-openapi-maven-plugin` fetches the spec and writes it to `target/openapi/openapi.yml`
132+
6. The SDK module uses `openapi-generator-maven-plugin` to generate typed API clients from the spec
133+
134+
### Usage in a Microservice
135+
136+
**1. Create `OpenApiGenApplication` in `src/test/java`:**
137+
138+
```java
139+
@EnableOpenApiGen
140+
@ComponentScan(basePackages = "com.firefly.your.module.web.controllers")
141+
public class OpenApiGenApplication {
142+
public static void main(String[] args) {
143+
SpringApplication.run(OpenApiGenApplication.class, args);
144+
}
145+
}
146+
```
147+
148+
**2. Add properties to the `-web` module's `pom.xml`:**
149+
150+
```xml
151+
<properties>
152+
<openapi.gen.skip>false</openapi.gen.skip>
153+
<openapi.gen.mainClass>com.firefly.your.module.web.openapi.OpenApiGenApplication</openapi.gen.mainClass>
154+
</properties>
155+
```
156+
157+
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.
158+
159+
## Documentation
116160

117161
## Contributing
118162

‎pom.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,13 @@
4343
<artifactId>swagger-annotations</artifactId>
4444
</dependency>
4545

46+
<!-- Mockito (optional — only needed at compile time for AutoMockMissingBeansConfig) -->
47+
<dependency>
48+
<groupId>org.mockito</groupId>
49+
<artifactId>mockito-core</artifactId>
50+
<optional>true</optional>
51+
</dependency>
52+
4653
<!-- Utils -->
4754
<dependency>
4855
<groupId>org.projectlombok</groupId>

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

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
/*
2+
* Copyright 2024-2026 Firefly Software Solutions Inc
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.fireflyframework.web.openapi;
18+
19+
import org.mockito.Mockito;
20+
import org.slf4j.Logger;
21+
import org.slf4j.LoggerFactory;
22+
import org.springframework.beans.BeansException;
23+
import org.springframework.beans.factory.annotation.Autowired;
24+
import org.springframework.beans.factory.config.BeanDefinition;
25+
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
26+
import org.springframework.beans.factory.support.BeanDefinitionRegistry;
27+
import org.springframework.beans.factory.support.BeanDefinitionRegistryPostProcessor;
28+
import org.springframework.context.annotation.Configuration;
29+
import org.springframework.context.annotation.Profile;
30+
import org.springframework.web.bind.annotation.RestController;
31+
32+
import java.lang.reflect.Constructor;
33+
import java.lang.reflect.Field;
34+
import java.util.LinkedHashMap;
35+
import java.util.Map;
36+
37+
/**
38+
* Automatically registers Mockito mock beans for every dependency of
39+
* {@code @RestController} classes that is not already present in the bean
40+
* registry. Supports both {@code @Autowired} field injection and
41+
* constructor injection.
42+
*
43+
* <p>Mocks are registered as pre-existing singletons via
44+
* {@link ConfigurableListableBeanFactory#registerSingleton} so that Spring
45+
* does not attempt to process {@code @Autowired} annotations on the mock
46+
* objects themselves (which would fail for concrete service classes that
47+
* have their own unsatisfied dependencies).
48+
*
49+
* <p>Activated only under the {@code openapi-gen} Spring profile.
50+
*/
51+
@Configuration
52+
@Profile("openapi-gen")
53+
public class AutoMockMissingBeansConfig implements BeanDefinitionRegistryPostProcessor {
54+
55+
private static final Logger logger = LoggerFactory.getLogger(AutoMockMissingBeansConfig.class);
56+
57+
private final Map<String, Class<?>> mocksToRegister = new LinkedHashMap<>();
58+
59+
@Override
60+
public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {
61+
for (String beanName : registry.getBeanDefinitionNames()) {
62+
BeanDefinition bd = registry.getBeanDefinition(beanName);
63+
String beanClassName = bd.getBeanClassName();
64+
if (beanClassName == null) {
65+
continue;
66+
}
67+
68+
Class<?> beanClass;
69+
try {
70+
beanClass = Class.forName(beanClassName);
71+
} catch (ClassNotFoundException e) {
72+
continue;
73+
}
74+
75+
if (!beanClass.isAnnotationPresent(RestController.class)) {
76+
continue;
77+
}
78+
79+
// Handle @Autowired field injection
80+
for (Field field : beanClass.getDeclaredFields()) {
81+
if (!field.isAnnotationPresent(Autowired.class)) {
82+
continue;
83+
}
84+
collectMissingBean(registry, field.getType());
85+
}
86+
87+
// Handle constructor injection
88+
Constructor<?>[] constructors = beanClass.getDeclaredConstructors();
89+
if (constructors.length == 1 && constructors[0].getParameterCount() > 0) {
90+
for (Class<?> paramType : constructors[0].getParameterTypes()) {
91+
collectMissingBean(registry, paramType);
92+
}
93+
}
94+
}
95+
}
96+
97+
@Override
98+
public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
99+
for (Map.Entry<String, Class<?>> entry : mocksToRegister.entrySet()) {
100+
Class<?> fieldType = entry.getValue();
101+
String mockBeanName = "mock_" + fieldType.getSimpleName();
102+
103+
logger.info("Registering Mockito mock singleton: {} (type: {})",
104+
mockBeanName, fieldType.getName());
105+
beanFactory.registerSingleton(mockBeanName, Mockito.mock(fieldType));
106+
}
107+
}
108+
109+
private void collectMissingBean(BeanDefinitionRegistry registry, Class<?> type) {
110+
if (mocksToRegister.containsKey(type.getName())) {
111+
return;
112+
}
113+
if (isBeanTypeRegistered(registry, type)) {
114+
return;
115+
}
116+
String mockBeanName = "mock_" + type.getSimpleName();
117+
logger.info("Will register Mockito mock for missing bean: {} (type: {})",
118+
mockBeanName, type.getName());
119+
mocksToRegister.put(type.getName(), type);
120+
}
121+
122+
private boolean isBeanTypeRegistered(BeanDefinitionRegistry registry, Class<?> type) {
123+
for (String name : registry.getBeanDefinitionNames()) {
124+
BeanDefinition bd = registry.getBeanDefinition(name);
125+
String className = bd.getBeanClassName();
126+
if (className == null) {
127+
continue;
128+
}
129+
try {
130+
Class<?> clazz = Class.forName(className);
131+
if (type.isAssignableFrom(clazz)) {
132+
return true;
133+
}
134+
} catch (ClassNotFoundException e) {
135+
// Skip
136+
}
137+
}
138+
return false;
139+
}
140+
}

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

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
/*
2+
* Copyright 2024-2026 Firefly Software Solutions Inc
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.fireflyframework.web.openapi;
18+
19+
import org.springdoc.core.configuration.SpringDocConfiguration;
20+
import org.springdoc.core.properties.SpringDocConfigProperties;
21+
import org.springdoc.webflux.core.configuration.SpringDocWebFluxConfiguration;
22+
import org.springframework.boot.SpringBootConfiguration;
23+
import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
24+
import org.springframework.boot.autoconfigure.admin.SpringApplicationAdminJmxAutoConfiguration;
25+
import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;
26+
import org.springframework.boot.autoconfigure.web.reactive.HttpHandlerAutoConfiguration;
27+
import org.springframework.boot.autoconfigure.web.reactive.ReactiveWebServerFactoryAutoConfiguration;
28+
import org.springframework.boot.autoconfigure.web.reactive.WebFluxAutoConfiguration;
29+
import org.springframework.web.reactive.config.EnableWebFlux;
30+
31+
import java.lang.annotation.ElementType;
32+
import java.lang.annotation.Inherited;
33+
import java.lang.annotation.Retention;
34+
import java.lang.annotation.RetentionPolicy;
35+
import java.lang.annotation.Target;
36+
37+
/**
38+
* Meta-annotation that configures a minimal Spring Boot application for
39+
* OpenAPI spec generation. Combines {@code @SpringBootConfiguration},
40+
* {@code @EnableWebFlux}, and all required auto-configurations for Springdoc
41+
* and WebFlux into a single annotation.
42+
*
43+
* <p>Usage in each microservice's {@code src/test/java}:
44+
* <pre>{@code
45+
* @EnableOpenApiGen
46+
* @ComponentScan(basePackages = "com.example.web.controllers")
47+
* public class OpenApiGenApplication {
48+
* public static void main(String[] args) {
49+
* SpringApplication.run(OpenApiGenApplication.class, args);
50+
* }
51+
* }
52+
* }</pre>
53+
*
54+
* <p>The annotated class only needs to add {@code @ComponentScan} pointing at
55+
* its controller package — everything else is handled by this annotation.
56+
*/
57+
@Target(ElementType.TYPE)
58+
@Retention(RetentionPolicy.RUNTIME)
59+
@Inherited
60+
@SpringBootConfiguration
61+
@EnableWebFlux
62+
@ImportAutoConfiguration({
63+
AutoMockMissingBeansConfig.class,
64+
SpringDocConfiguration.class,
65+
SpringDocConfigProperties.class,
66+
SpringDocWebFluxConfiguration.class,
67+
ReactiveWebServerFactoryAutoConfiguration.class,
68+
HttpHandlerAutoConfiguration.class,
69+
WebFluxAutoConfiguration.class,
70+
JacksonAutoConfiguration.class,
71+
SpringApplicationAdminJmxAutoConfiguration.class
72+
})
73+
public @interface EnableOpenApiGen {
74+
}

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
spring:
2+
main:
3+
allow-bean-definition-overriding: true
4+
springdoc:
5+
api-docs:
6+
enabled: true
7+
version: openapi_3_0

0 commit comments

Comments
 (0)