diff --git a/.ai/mcp/mcp.json b/.ai/mcp/mcp.json
new file mode 100644
index 0000000..e69de29
diff --git a/.idea/misc.xml b/.idea/misc.xml
index 64a39dc..ff846ff 100644
--- a/.idea/misc.xml
+++ b/.idea/misc.xml
@@ -13,6 +13,11 @@
+
diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 6f89113..206108b 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -5,61 +5,26 @@
+
-
-
-
+
+
-
+
+
-
-
-
-
-
+
+
-
-
-
-
-
-
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
@@ -74,7 +39,7 @@
-
+
@@ -95,12 +60,12 @@
"assignee": "Relism"
}
}
- {
+ "selectedUrlAndAccountId": {
+ "url": "https://github.com/Relism/Flash5.git",
+ "accountId": "86d8a39c-af27-4b79-8d5d-dc74375c3348"
}
-}]]>
+}
@@ -116,62 +81,62 @@
- {
+ "keyToString": {
+ "Application.(dev) flash-bench.executor": "Run",
+ "Application.ExternalBenchmark (1).executor": "Run",
+ "Application.ExternalBenchmark.executor": "Run",
+ "Application.Main.executor": "Run",
+ "Application.MainAlt.executor": "Run",
+ "Application.dev.relism.bench.Main.executor": "Run",
+ "JUnit.RequestParserTest.executor": "Run",
+ "JUnit.RequestParserTest.headers_caseInsensitive.executor": "Debug",
+ "Maven.FlashPractice [test].executor": "Run",
+ "Maven.flash [compile].executor": "Run",
+ "Maven.flash [install].executor": "Run",
+ "Maven.flash [test].executor": "Run",
+ "Maven.flash [verify].executor": "Run",
+ "Maven.flash-bench [clean].executor": "Run",
+ "Maven.flash-bench [install].executor": "Run",
+ "Maven.flash-bench [package].executor": "Run",
+ "Maven.flash-bench [validate].executor": "Run",
+ "Maven.flash-ext-limiter [install].executor": "Run",
+ "Maven.flash-ext-limiter [package].executor": "Run",
+ "Maven.flash-ext-view [verify].executor": "Run",
+ "Maven.flash-parent [clean].executor": "Run",
+ "Maven.flash-parent [compile].executor": "Run",
+ "Maven.flash-parent [deploy].executor": "Run",
+ "Maven.flash-parent [install].executor": "Run",
+ "Maven.flash-parent [package].executor": "Run",
+ "Maven.flash-parent [verify].executor": "Run",
+ "Maven.flash-web-bundler [test].executor": "Run",
+ "ModuleVcsDetector.initialDetectionPerformed": "true",
+ "RunOnceActivity.MCP Project settings loaded": "true",
+ "RunOnceActivity.ShowReadmeOnStart": "true",
+ "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+ "RunOnceActivity.git.unshallow": "true",
+ "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+ "SHARE_PROJECT_CONFIGURATION_FILES": "true",
+ "codeWithMe.voiceChat.enabledByDefault": "false",
+ "git-widget-placeholder": "master",
+ "ignore.virus.scanning.warn.message": "true",
+ "kotlin-language-version-configured": "true",
+ "last_opened_file_path": "C:/Users/elorc/Documents/Coding/Java/practice/Flash",
+ "node.js.detected.package.eslint": "true",
+ "node.js.detected.package.tslint": "true",
+ "node.js.selected.package.eslint": "(autodetect)",
+ "node.js.selected.package.tslint": "(autodetect)",
+ "nodejs_package_manager_path": "npm",
+ "npm.build.executor": "Run",
+ "onboarding.tips.debug.path": "C:/Users/elorc/Documents/Coding/Java/practice/FlashPractice/flash-bench/src/main/java/dev/relism/Main.java",
+ "project.structure.last.edited": "Modules",
+ "project.structure.proportion": "0.15",
+ "project.structure.side.proportion": "0.1150748",
+ "settings.editor.selected.configurable": "project.propVCSSupport.DirectoryMappings",
+ "ts.external.directory.path": "C:\\Users\\elorc\\Documents\\Coding\\Java\\practice\\Flash\\nuxt-shadcn-dashboard\\node_modules\\typescript\\lib",
+ "vue.rearranger.settings.migration": "true"
}
-}]]>
+}
@@ -299,6 +264,8 @@
+
+
diff --git a/flash-extensions/flash-ext-limiter/docs/annotation.md b/flash-extensions/flash-ext-limiter/docs/annotation.md
index 8523a7a..35006d1 100644
--- a/flash-extensions/flash-ext-limiter/docs/annotation.md
+++ b/flash-extensions/flash-ext-limiter/docs/annotation.md
@@ -92,6 +92,9 @@ public class PriceHandler extends RequestHandler { ... }
Each annotation is processed by its own processor; Flash collects all middleware and
composes them in processor registration order.
+When `flash-ext-openapi` is installed, `@Limit` also contributes OpenAPI response
+headers (`X-RateLimit-*`) and `Retry-After` on `429` automatically.
+
```java
@Route(method = HttpMethod.DELETE, path = "/admin/users/{id}")
@Limit(key = "auth_user", requests = 5, window = 1, windowUnit = TimeUnit.MINUTES)
diff --git a/flash-extensions/flash-ext-limiter/docs/http-headers.md b/flash-extensions/flash-ext-limiter/docs/http-headers.md
index 1d91443..42f7772 100644
--- a/flash-extensions/flash-ext-limiter/docs/http-headers.md
+++ b/flash-extensions/flash-ext-limiter/docs/http-headers.md
@@ -117,6 +117,12 @@ and **instead of** calling it on rejected requests. This means:
## Integration with Swagger UI (flash-ext-openapi)
-Rate-limit headers are not currently injected into the OpenAPI spec. If you want to
-document them, add them manually via `@ApiOperation` on the handler class using the
-response headers section of the OpenAPI spec.
+When `flash-ext-openapi` is installed, handlers annotated with `@Limit` automatically
+contribute rate-limit response headers to generated OpenAPI responses:
+
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`
+- `Retry-After` on `429`
+
+If `429` is not manually declared, OpenAPI auto-adds `429 Too Many Requests`.
diff --git a/flash-extensions/flash-ext-limiter/pom.xml b/flash-extensions/flash-ext-limiter/pom.xml
index f339e5a..c1ac619 100644
--- a/flash-extensions/flash-ext-limiter/pom.xml
+++ b/flash-extensions/flash-ext-limiter/pom.xml
@@ -17,6 +17,11 @@
dev.relismflash
+
+ dev.relism
+ flash-ext-openapi
+ true
+ org.projectlomboklombok
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java
index c1b5e0e..896e43b 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java
@@ -1,13 +1,18 @@
package dev.relism.ext.limiter;
+import dev.relism.ext.openapi.OpenApiContributorRegistry;
+import dev.relism.ext.openapi.OpenApiOperationContribution;
+import dev.relism.ext.openapi.OpenApiResponseContribution;
import dev.relism.extension.ExtensionPhase;
import dev.relism.extension.FlashContext;
import dev.relism.extension.FlashExtension;
+import dev.relism.extension.FlashRegistrar;
import dev.relism.http.HttpStatus;
import dev.relism.routing.Middleware;
import java.nio.charset.StandardCharsets;
import java.util.List;
+import java.util.Map;
/**
* Rate-limiting extension for Flash.
@@ -87,6 +92,15 @@ public final class LimiterExtension implements FlashExtension {
});
}
+ @Override
+ public void routes(FlashRegistrar app, FlashContext ctx) {
+ try {
+ OpenApiIntegration.register(ctx);
+ } catch (NoClassDefFoundError ignored) {
+ // flash-ext-openapi not available — OpenAPI integration disabled
+ }
+ }
+
// ── Package-private helper — shared with Guard ────────────────────────────
/**
@@ -126,4 +140,57 @@ public final class LimiterExtension implements FlashExtension {
return next.handle(req, res);
};
}
+
+ private static final class OpenApiIntegration {
+ private static final Map INTEGER_SCHEMA = Map.of("type", "integer");
+ private static final Map LIMIT_HEADER = Map.of(
+ "description", "Maximum requests allowed in current window",
+ "schema", INTEGER_SCHEMA
+ );
+ private static final Map REMAINING_HEADER = Map.of(
+ "description", "Requests remaining in current window",
+ "schema", INTEGER_SCHEMA
+ );
+ private static final Map RESET_HEADER = Map.of(
+ "description", "Unix epoch seconds when quota resets or next token arrives",
+ "schema", INTEGER_SCHEMA
+ );
+ private static final Map RETRY_AFTER_HEADER = Map.of(
+ "description", "Seconds to wait before retrying",
+ "schema", INTEGER_SCHEMA
+ );
+
+ static void register(FlashContext ctx) {
+ ctx.find(OpenApiContributorRegistry.class)
+ .ifPresent(registry -> registry.add(new dev.relism.ext.openapi.OpenApiContributor() {
+ @Override
+ public dev.relism.ext.openapi.OpenApiOperationContribution operationFor(Class handlerClass) {
+ if (handlerClass.getAnnotation(Limit.class) == null) {
+ return OpenApiOperationContribution.builder().build();
+ }
+
+ OpenApiResponseContribution common =
+ OpenApiResponseContribution.builder()
+ .header("X-RateLimit-Limit", LIMIT_HEADER)
+ .header("X-RateLimit-Remaining", REMAINING_HEADER)
+ .header("X-RateLimit-Reset", RESET_HEADER)
+ .build();
+
+ OpenApiResponseContribution tooManyRequests =
+ OpenApiResponseContribution.builder()
+ .description("Too Many Requests")
+ .header("X-RateLimit-Limit", LIMIT_HEADER)
+ .header("X-RateLimit-Remaining", REMAINING_HEADER)
+ .header("X-RateLimit-Reset", RESET_HEADER)
+ .header("Retry-After", RETRY_AFTER_HEADER)
+ .build();
+
+ return OpenApiOperationContribution.builder()
+ .allResponses(common)
+ .response(429, tooManyRequests)
+ .build();
+ }
+ }));
+ }
+ }
}
diff --git a/flash-extensions/flash-ext-limiter/src/test/java/dev/relism/ext/limiter/LimiterOpenApiInteropTest.java b/flash-extensions/flash-ext-limiter/src/test/java/dev/relism/ext/limiter/LimiterOpenApiInteropTest.java
new file mode 100644
index 0000000..37b5aa4
--- /dev/null
+++ b/flash-extensions/flash-ext-limiter/src/test/java/dev/relism/ext/limiter/LimiterOpenApiInteropTest.java
@@ -0,0 +1,84 @@
+package dev.relism.ext.limiter;
+
+import dev.relism.ext.openapi.OpenApiContributor;
+import dev.relism.ext.openapi.OpenApiContributorRegistry;
+import dev.relism.ext.openapi.OpenApiOperationContribution;
+import dev.relism.ext.openapi.OpenApiResponseContribution;
+import dev.relism.extension.FlashContext;
+import dev.relism.models.Request;
+import dev.relism.models.RequestHandler;
+import dev.relism.models.Response;
+import dev.relism.routing.GET;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class LimiterOpenApiInteropTest {
+
+ @GET("/limited")
+ @Limit(requests = 10, window = 1)
+ static class LimitedHandler extends RequestHandler {
+ @Override
+ public Object handle(Request request, Response response) {
+ return null;
+ }
+ }
+
+ @GET("/plain")
+ static class PlainHandler extends RequestHandler {
+ @Override
+ public Object handle(Request request, Response response) {
+ return null;
+ }
+ }
+
+ @Test
+ void registersContributor_whenOpenApiRegistryExists() {
+ FlashContext ctx = new FlashContext();
+ OpenApiContributorRegistry registry = new OpenApiContributorRegistry();
+ ctx.provide(OpenApiContributorRegistry.class, registry);
+
+ new LimiterExtension().routes(null, ctx);
+
+ assertEquals(1, registry.contributors().size());
+ }
+
+ @Test
+ void limitedHandler_contributesHeadersAnd429() {
+ FlashContext ctx = new FlashContext();
+ OpenApiContributorRegistry registry = new OpenApiContributorRegistry();
+ ctx.provide(OpenApiContributorRegistry.class, registry);
+ new LimiterExtension().routes(null, ctx);
+
+ OpenApiContributor contributor = registry.contributors().getFirst();
+ OpenApiOperationContribution operation = contributor.operationFor(LimitedHandler.class);
+
+ OpenApiResponseContribution all = operation.allResponses();
+ assertNotNull(all);
+ assertTrue(all.headers().containsKey("X-RateLimit-Limit"));
+ assertTrue(all.headers().containsKey("X-RateLimit-Remaining"));
+ assertTrue(all.headers().containsKey("X-RateLimit-Reset"));
+
+ OpenApiResponseContribution tooMany = operation.responses().get(429);
+ assertNotNull(tooMany);
+ assertEquals("Too Many Requests", tooMany.description());
+ assertTrue(tooMany.headers().containsKey("Retry-After"));
+ }
+
+ @Test
+ void plainHandler_hasNoContribution() {
+ FlashContext ctx = new FlashContext();
+ OpenApiContributorRegistry registry = new OpenApiContributorRegistry();
+ ctx.provide(OpenApiContributorRegistry.class, registry);
+ new LimiterExtension().routes(null, ctx);
+
+ OpenApiContributor contributor = registry.contributors().getFirst();
+ OpenApiOperationContribution operation = contributor.operationFor(PlainHandler.class);
+
+ assertTrue(operation.isEmpty());
+ assertFalse(operation.responses().containsKey(429));
+ }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
index a019bf1..f447dd7 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
@@ -263,62 +263,64 @@ public class OidcExtension implements FlashExtension {
/**
* Loaded lazily so that {@code flash-ext-openapi} classes are only resolved at
- * runtime when {@link dev.relism.ext.openapi.OpenApiSecurityRegistry} is actually on the classpath.
+ * runtime when {@link dev.relism.ext.openapi.OpenApiContributorRegistry} is actually on the classpath.
*/
private static final class OpenApiIntegration {
static void register(dev.relism.extension.FlashContext ctx,
OidcConfig config, OidcProviderMetadata meta) {
- ctx.find(dev.relism.ext.openapi.OpenApiSecurityRegistry.class)
- .ifPresent(registry -> registry.add(new dev.relism.ext.openapi.OpenApiSecurityContributor() {
+ ctx.find(dev.relism.ext.openapi.OpenApiContributorRegistry.class)
+ .ifPresent(registry -> registry.add(new dev.relism.ext.openapi.OpenApiContributor() {
- @Override
- public String schemeName() { return config.schemeName(); }
-
- @Override
- public java.util.Map schemeDefinition() {
- java.util.Map scopesMap = new java.util.LinkedHashMap<>();
- for (String s : config.scopes().split("\\s+")) {
- if (!s.isBlank()) scopesMap.put(s, s);
+ @Override
+ public java.util.Map componentContributions() {
+ java.util.Map scopesMap = new java.util.LinkedHashMap<>();
+ for (String s : config.scopes().split("\\s+")) {
+ if (!s.isBlank()) scopesMap.put(s, s);
}
java.util.Map flow = new java.util.LinkedHashMap<>();
flow.put("authorizationUrl", meta.authorizationEndpoint());
flow.put("tokenUrl", meta.tokenEndpoint());
- flow.put("scopes", scopesMap);
+ flow.put("scopes", scopesMap);
- java.util.Map scheme = new java.util.LinkedHashMap<>();
- scheme.put("type", "oauth2");
- scheme.put("flows", java.util.Map.of("authorizationCode", flow));
- return scheme;
- }
+ java.util.Map scheme = new java.util.LinkedHashMap<>();
+ scheme.put("type", "oauth2");
+ scheme.put("flows", java.util.Map.of("authorizationCode", flow));
- @Override
- public java.util.List requiredFor(Class handlerClass) {
- return OidcAuthPolicy.openApiScopesFor(handlerClass);
+ java.util.Map securitySchemes = new java.util.LinkedHashMap<>();
+ securitySchemes.put(config.schemeName(), scheme);
+ return java.util.Map.of("securitySchemes", securitySchemes);
}
- @Override
- public java.util.Map autoResponsesFor(Class handlerClass) {
- OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(handlerClass);
- if (policy == null || policy.optionalAuth()) return java.util.Map.of();
+ @Override
+ public dev.relism.ext.openapi.OpenApiOperationContribution operationFor(Class handlerClass) {
+ dev.relism.ext.openapi.OpenApiOperationContribution.Builder out =
+ dev.relism.ext.openapi.OpenApiOperationContribution.builder();
- java.util.LinkedHashMap out = new java.util.LinkedHashMap<>();
- out.put(401, "Authentication required");
+ java.util.List operationScopes = OidcAuthPolicy.openApiScopesFor(handlerClass);
+ if (operationScopes != null) {
+ out.security(config.schemeName(), operationScopes);
+ }
+
+ OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(handlerClass);
+ if (policy == null || policy.optionalAuth()) return out.build();
+
+ out.response(401, dev.relism.ext.openapi.OpenApiResponseContribution.of("Authentication required"));
String[] roles = policy.requiredRoles();
String[] scopes = policy.requiredScopes();
- if (roles.length == 0 && scopes.length == 0) return out;
+ if (roles.length == 0 && scopes.length == 0) return out.build();
String roleMessage = roles.length == 0 ? null : roleRequiredMessage(roles);
String scopeMessage = scopes.length == 0 ? null : scopeRequiredMessage(scopes);
if (roleMessage != null && scopeMessage != null) {
- out.put(403, roleMessage + "; " + scopeMessage);
+ out.response(403, dev.relism.ext.openapi.OpenApiResponseContribution.of(roleMessage + "; " + scopeMessage));
} else if (roleMessage != null) {
- out.put(403, roleMessage);
+ out.response(403, dev.relism.ext.openapi.OpenApiResponseContribution.of(roleMessage));
} else {
- out.put(403, scopeMessage);
+ out.response(403, dev.relism.ext.openapi.OpenApiResponseContribution.of(scopeMessage));
}
- return out;
- }
+ return out.build();
+ }
}));
}
diff --git a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcOpenApiInteropTest.java b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcOpenApiInteropTest.java
index 1035d51..e199d04 100644
--- a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcOpenApiInteropTest.java
+++ b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcOpenApiInteropTest.java
@@ -1,10 +1,11 @@
package dev.relism.ext.oidc;
-import dev.relism.ext.openapi.OpenApiSecurityContributor;
+import dev.relism.ext.openapi.OpenApiContributor;
import org.junit.jupiter.api.Test;
import java.lang.reflect.Constructor;
import java.lang.reflect.Method;
+import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -37,49 +38,57 @@ class OidcOpenApiInteropTest {
@Test
void autoResponses_authOnly() throws Exception {
- Map responses = contributor().autoResponsesFor(AuthOnly.class);
+ Map responses = responses(AuthOnly.class);
assertEquals("Authentication required", responses.get(401));
assertFalse(responses.containsKey(403));
}
@Test
void autoResponses_optionalAuth_addsNothing() throws Exception {
- Map responses = contributor().autoResponsesFor(AuthOptional.class);
+ Map responses = responses(AuthOptional.class);
assertTrue(responses.isEmpty());
}
@Test
void autoResponses_oneRole_formatsSingular() throws Exception {
- Map responses = contributor().autoResponsesFor(OneRole.class);
+ Map responses = responses(OneRole.class);
assertEquals("Authentication required", responses.get(401));
assertEquals("\"admin\" role required", responses.get(403));
}
@Test
void autoResponses_multiRoles_formatsPlural() throws Exception {
- Map responses = contributor().autoResponsesFor(MultiRole.class);
+ Map responses = responses(MultiRole.class);
assertEquals("Roles \"admin, operator\" are required", responses.get(403));
}
@Test
void autoResponses_oneScope_formatsSingular() throws Exception {
- Map responses = contributor().autoResponsesFor(OneScope.class);
+ Map responses = responses(OneScope.class);
assertEquals("\"orders:write\" scope required", responses.get(403));
}
@Test
void autoResponses_multiScopes_formatsPlural() throws Exception {
- Map responses = contributor().autoResponsesFor(MultiScope.class);
+ Map responses = responses(MultiScope.class);
assertEquals("Scopes \"orders:write, payments:write\" are required", responses.get(403));
}
@Test
void autoResponses_roleAndScope_combinesMessages() throws Exception {
- Map responses = contributor().autoResponsesFor(RoleAndScope.class);
+ Map responses = responses(RoleAndScope.class);
assertEquals("\"admin\" role required; \"orders:write\" scope required", responses.get(403));
}
- private static OpenApiSecurityContributor contributor() throws Exception {
+ @Test
+ void securityContribution_presentForAuthenticatedHandler() throws Exception {
+ dev.relism.ext.openapi.OpenApiOperationContribution operation = contributor().operationFor(AuthOnly.class);
+ List>> security = operation.security();
+ assertEquals(1, security.size());
+ assertTrue(security.getFirst().containsKey("issuer"));
+ }
+
+ private static OpenApiContributor contributor() throws Exception {
Class clazz = Class.forName("dev.relism.ext.oidc.OidcExtension$OpenApiIntegration");
Constructor ctor = clazz.getDeclaredConstructor();
ctor.setAccessible(true);
@@ -89,8 +98,8 @@ class OidcOpenApiInteropTest {
m.setAccessible(true);
dev.relism.extension.FlashContext ctx = new dev.relism.extension.FlashContext();
- dev.relism.ext.openapi.OpenApiSecurityRegistry registry = new dev.relism.ext.openapi.OpenApiSecurityRegistry();
- ctx.provide(dev.relism.ext.openapi.OpenApiSecurityRegistry.class, registry);
+ dev.relism.ext.openapi.OpenApiContributorRegistry registry = new dev.relism.ext.openapi.OpenApiContributorRegistry();
+ ctx.provide(dev.relism.ext.openapi.OpenApiContributorRegistry.class, registry);
OidcConfig config = OidcConfig.builder("https://issuer", "c", "s", "/cb").build();
OidcProviderMetadata meta = new OidcProviderMetadata("a", "t", "u", "j", "e");
@@ -98,4 +107,13 @@ class OidcOpenApiInteropTest {
return registry.contributors().getFirst();
}
+
+ private static Map responses(Class cls) throws Exception {
+ Map byCode = contributor().operationFor(cls).responses();
+ java.util.LinkedHashMap out = new java.util.LinkedHashMap<>();
+ for (Map.Entry e : byCode.entrySet()) {
+ out.put(e.getKey(), e.getValue().description());
+ }
+ return out;
+ }
}
diff --git a/flash-extensions/flash-ext-openapi/README.md b/flash-extensions/flash-ext-openapi/README.md
index fe096ae..b49159c 100644
--- a/flash-extensions/flash-ext-openapi/README.md
+++ b/flash-extensions/flash-ext-openapi/README.md
@@ -105,6 +105,22 @@ Supported field-level exclusion:
- `@JsonIgnoreProperties(...)`
- `transient` / `static`
+## Contributor API
+
+OpenAPI is extension-agnostic. Other extensions contribute with `OpenApiContributor` via
+`OpenApiContributorRegistry`.
+
+Supported contribution surfaces:
+
+- `components` fragments (merged with last-wins)
+- operation `security` requirements (additive)
+- operation `responses` and response `headers` (additive)
+
+Merge policy:
+
+- contributor collisions use **last-wins**
+- manual `@APIResponse` description always wins over contributors for the same status
+
## OIDC interop
When `flash-ext-oidc` is installed, OpenAPI integrates automatically:
@@ -117,6 +133,18 @@ When `flash-ext-oidc` is installed, OpenAPI integrates automatically:
Manual `@APIResponse` for the same status code always wins.
+## Limiter interop
+
+When `flash-ext-limiter` is installed, handlers with `@Limit` automatically get response
+headers documented in OpenAPI:
+
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`
+- `Retry-After` on `429`
+
+If `429` is missing, it is auto-added as `Too Many Requests`.
+
## Notes
- Operations are collected from final boot-time routes for class-based handlers with `@ApiOperation`.
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/APIResponse.java
similarity index 100%
rename from flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java
rename to flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/APIResponse.java
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponses.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/APIResponses.java
similarity index 100%
rename from flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponses.java
rename to flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/APIResponses.java
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
index 76f278b..84a2357 100644
--- a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
@@ -51,7 +51,7 @@ public final class OpenApiBuilder {
private final Map> paths = new LinkedHashMap<>();
private final Map>> operationHandlers = new LinkedHashMap<>();
private final SchemaRegistry schemas = new SchemaRegistry();
- private OpenApiSecurityRegistry securityRegistry;
+ private OpenApiContributorRegistry contributorRegistry;
private int revision;
private int builtRevision = -1;
private Map cachedSpec;
@@ -59,7 +59,7 @@ public final class OpenApiBuilder {
public OpenApiBuilder title(String title) { this.title = title; return this; }
public OpenApiBuilder version(String version) { this.version = version; return this; }
public OpenApiBuilder description(String description) { this.description = description; return this; }
- void setSecurityRegistry(OpenApiSecurityRegistry registry) { this.securityRegistry = registry; }
+ void setContributorRegistry(OpenApiContributorRegistry registry) { this.contributorRegistry = registry; }
public void addOperation(Route route, ApiOperation op, Class handlerClass) {
String path = normalizePath(route.path());
@@ -90,8 +90,8 @@ public final class OpenApiBuilder {
info.put("version", version);
if (!description.isEmpty()) info.put("description", description);
- List contributors = securityRegistry != null
- ? securityRegistry.contributors() : List.of();
+ List contributors = contributorRegistry != null
+ ? contributorRegistry.contributors() : List.of();
Map renderedPaths = new LinkedHashMap<>();
for (var pathEntry : paths.entrySet()) {
@@ -103,8 +103,7 @@ public final class OpenApiBuilder {
Map op = new LinkedHashMap<>(original);
Class handler = handlers.get(methodEntry.getKey());
if (handler != null && !contributors.isEmpty()) {
- List>> security = buildOperationSecurity(contributors, handler);
- if (!security.isEmpty()) op.put("security", security);
+ applyContributorOperation(op, handler, contributors);
}
renderedPathItem.put(methodEntry.getKey(), op);
}
@@ -119,11 +118,7 @@ public final class OpenApiBuilder {
Map components = new LinkedHashMap<>();
Map renderedSchemas = schemas.render();
if (!renderedSchemas.isEmpty()) components.put("schemas", renderedSchemas);
- if (!contributors.isEmpty()) {
- Map securitySchemes = new LinkedHashMap<>();
- for (OpenApiSecurityContributor c : contributors) securitySchemes.put(c.schemeName(), c.schemeDefinition());
- components.put("securitySchemes", securitySchemes);
- }
+ if (!contributors.isEmpty()) applyContributorComponents(components, contributors);
if (!components.isEmpty()) spec.put("components", components);
cachedSpec = spec;
@@ -181,16 +176,12 @@ public final class OpenApiBuilder {
responseByCode.put(code, buildAnnotatedResponse(code, ann, cls));
}
- for (OpenApiSecurityContributor c : securityContributors()) {
- for (var auto : c.autoResponsesFor(cls).entrySet()) {
- responseByCode.putIfAbsent(auto.getKey(), Map.of("description", auto.getValue()));
- }
- }
-
if (responseByCode.isEmpty()) {
responseByCode.put(200, Map.of("description", "OK"));
}
+ applyContributorResponses(responseByCode, cls);
+
Map responses = new LinkedHashMap<>();
responseByCode.entrySet().stream()
.sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
@@ -198,8 +189,97 @@ public final class OpenApiBuilder {
op.put("responses", responses);
}
- private List securityContributors() {
- return securityRegistry != null ? securityRegistry.contributors() : List.of();
+ private List contributors() {
+ return contributorRegistry != null ? contributorRegistry.contributors() : List.of();
+ }
+
+ private void applyContributorResponses(Map> responseByCode, Class handlerClass) {
+ APIResponse[] manual = handlerClass.getAnnotationsByType(APIResponse.class);
+ Set manualStatusCodes = new HashSet<>();
+ for (APIResponse ann : manual) {
+ manualStatusCodes.add(parseStatus(ann.responseCode()));
+ }
+
+ for (OpenApiContributor contributor : contributors()) {
+ OpenApiOperationContribution contribution = contributor.operationFor(handlerClass);
+ if (contribution == null) continue;
+
+ for (Map.Entry entry : contribution.responses().entrySet()) {
+ int status = entry.getKey();
+ OpenApiResponseContribution responseContribution = entry.getValue();
+ if (responseContribution == null) continue;
+
+ Map response = responseByCode.computeIfAbsent(status, __ -> new LinkedHashMap<>());
+ mergeContributorResponse(response, responseContribution, status, manualStatusCodes);
+ }
+
+ OpenApiResponseContribution allResponses = contribution.allResponses();
+ if (allResponses != null) {
+ for (Map.Entry> entry : responseByCode.entrySet()) {
+ mergeContributorResponse(entry.getValue(), allResponses, entry.getKey(), manualStatusCodes);
+ }
+ }
+ }
+ }
+
+ private static void mergeContributorResponse(Map response,
+ OpenApiResponseContribution contribution,
+ int status,
+ Set manualStatusCodes) {
+ String desc = contribution.description();
+ if (!manualStatusCodes.contains(status) && desc != null && !desc.isBlank()) {
+ response.put("description", desc);
+ }
+
+ Map> headerContributions = contribution.headers();
+ if (!headerContributions.isEmpty()) {
+ @SuppressWarnings("unchecked")
+ Map headers = (Map) response.computeIfAbsent("headers", __ -> new LinkedHashMap<>());
+ for (Map.Entry> h : headerContributions.entrySet()) {
+ headers.put(h.getKey(), new LinkedHashMap<>(h.getValue()));
+ }
+ }
+
+ if (!response.containsKey("description")) {
+ response.put("description", defaultDescription(status));
+ }
+ }
+
+ private static void applyContributorComponents(Map components, List contributors) {
+ for (OpenApiContributor contributor : contributors) {
+ Map c = contributor.componentContributions();
+ if (c == null || c.isEmpty()) continue;
+ deepMergeLastWins(components, c);
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private static void deepMergeLastWins(Map target, Map incoming) {
+ for (Map.Entry e : incoming.entrySet()) {
+ Object existing = target.get(e.getKey());
+ Object value = e.getValue();
+ if (existing instanceof Map em && value instanceof Map vm) {
+ Map merged = new LinkedHashMap<>((Map) em);
+ deepMergeLastWins(merged, (Map) vm);
+ target.put(e.getKey(), merged);
+ } else {
+ target.put(e.getKey(), value);
+ }
+ }
+ }
+
+ private void applyContributorOperation(Map op, Class handlerClass, List contributors) {
+ for (OpenApiContributor contributor : contributors) {
+ OpenApiOperationContribution contribution = contributor.operationFor(handlerClass);
+ if (contribution == null || contribution.isEmpty()) continue;
+
+ if (!contribution.security().isEmpty()) {
+ @SuppressWarnings("unchecked")
+ List>> security = (List>>) op
+ .computeIfAbsent("security", __ -> new ArrayList<>());
+ security.addAll(contribution.security());
+ }
+ }
}
private Map buildAnnotatedResponse(int code, APIResponse ann, Class handlerClass) {
@@ -272,16 +352,6 @@ public final class OpenApiBuilder {
return reason == null ? "" : reason;
}
- private static List>> buildOperationSecurity(List contributors,
- Class handlerClass) {
- List>> security = new ArrayList<>();
- for (OpenApiSecurityContributor c : contributors) {
- List scopes = c.requiredFor(handlerClass);
- if (scopes != null) security.add(Map.of(c.schemeName(), scopes));
- }
- return security;
- }
-
private static Class rawType(Type type) {
if (type instanceof Class c) return c;
if (type instanceof ParameterizedType p && p.getRawType() instanceof Class c) return c;
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiContributor.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiContributor.java
new file mode 100644
index 0000000..19c9d2a
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiContributor.java
@@ -0,0 +1,14 @@
+package dev.relism.ext.openapi;
+
+import java.util.Map;
+
+public interface OpenApiContributor {
+
+ default Map componentContributions() {
+ return Map.of();
+ }
+
+ default OpenApiOperationContribution operationFor(Class handlerClass) {
+ return OpenApiOperationContribution.empty();
+ }
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiContributorRegistry.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiContributorRegistry.java
new file mode 100644
index 0000000..f3b5e30
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiContributorRegistry.java
@@ -0,0 +1,17 @@
+package dev.relism.ext.openapi;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+public final class OpenApiContributorRegistry {
+ private final List contributors = new CopyOnWriteArrayList<>();
+
+ public void add(OpenApiContributor contributor) {
+ contributors.add(contributor);
+ }
+
+ public List contributors() {
+ return Collections.unmodifiableList(contributors);
+ }
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
index 8c7ce8c..b7c52a2 100644
--- a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
@@ -65,12 +65,12 @@ public class OpenApiExtension implements FlashExtension {
@Override
public void provide(FlashContext ctx) {
- OpenApiBuilder builder = new OpenApiBuilder().title(title).version(version).description(description);
- OpenApiSecurityRegistry secRegistry = new OpenApiSecurityRegistry();
+ OpenApiBuilder builder = new OpenApiBuilder().title(title).version(version).description(description);
+ OpenApiContributorRegistry registry = new OpenApiContributorRegistry();
- ctx.provide(OpenApiSecurityRegistry.class, secRegistry);
- ctx.provide(OpenApiBuilder.class, builder);
- builder.setSecurityRegistry(secRegistry);
+ ctx.provide(OpenApiContributorRegistry.class, registry);
+ ctx.provide(OpenApiBuilder.class, builder);
+ builder.setContributorRegistry(registry);
// Collect operation metadata from final compiled routes.
// This guarantees full runtime paths (namespaces/prefixes/rewrites) in the spec.
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiOperationContribution.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiOperationContribution.java
new file mode 100644
index 0000000..a0d9793
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiOperationContribution.java
@@ -0,0 +1,71 @@
+package dev.relism.ext.openapi;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+public final class OpenApiOperationContribution {
+ private static final OpenApiOperationContribution EMPTY = new OpenApiOperationContribution(List.of(), Map.of(), null);
+
+ private final List>> security;
+ private final Map responses;
+ private final OpenApiResponseContribution allResponses;
+
+ private OpenApiOperationContribution(List>> security,
+ Map responses,
+ OpenApiResponseContribution allResponses) {
+ this.security = List.copyOf(security);
+ this.responses = Map.copyOf(responses);
+ this.allResponses = allResponses;
+ }
+
+ public List>> security() {
+ return security;
+ }
+
+ public Map responses() {
+ return responses;
+ }
+
+ public OpenApiResponseContribution allResponses() {
+ return allResponses;
+ }
+
+ public boolean isEmpty() {
+ return security.isEmpty() && responses.isEmpty() && allResponses == null;
+ }
+
+ public static OpenApiOperationContribution empty() {
+ return EMPTY;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public static final class Builder {
+ private final List>> security = new ArrayList<>();
+ private final Map responses = new LinkedHashMap<>();
+ private OpenApiResponseContribution allResponses;
+
+ public Builder security(String schemeName, List scopes) {
+ security.add(Map.of(schemeName, List.copyOf(scopes)));
+ return this;
+ }
+
+ public Builder response(int statusCode, OpenApiResponseContribution response) {
+ responses.put(statusCode, response);
+ return this;
+ }
+
+ public Builder allResponses(OpenApiResponseContribution response) {
+ this.allResponses = response;
+ return this;
+ }
+
+ public OpenApiOperationContribution build() {
+ return new OpenApiOperationContribution(security, responses, allResponses);
+ }
+ }
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiResponseContribution.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiResponseContribution.java
new file mode 100644
index 0000000..e1a73d7
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiResponseContribution.java
@@ -0,0 +1,49 @@
+package dev.relism.ext.openapi;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+public final class OpenApiResponseContribution {
+ private final String description;
+ private final Map> headers;
+
+ private OpenApiResponseContribution(String description, Map> headers) {
+ this.description = description;
+ this.headers = Map.copyOf(headers);
+ }
+
+ public String description() {
+ return description;
+ }
+
+ public Map> headers() {
+ return headers;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public static OpenApiResponseContribution of(String description) {
+ return builder().description(description).build();
+ }
+
+ public static final class Builder {
+ private String description;
+ private final Map> headers = new LinkedHashMap<>();
+
+ public Builder description(String description) {
+ this.description = description;
+ return this;
+ }
+
+ public Builder header(String name, Map headerObject) {
+ headers.put(name, Map.copyOf(headerObject));
+ return this;
+ }
+
+ public OpenApiResponseContribution build() {
+ return new OpenApiResponseContribution(description, headers);
+ }
+ }
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java
deleted file mode 100644
index c33aae5..0000000
--- a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java
+++ /dev/null
@@ -1,57 +0,0 @@
-package dev.relism.ext.openapi;
-
-import java.util.List;
-import java.util.Map;
-
-/**
- * Pluggable security scheme contributor for the OpenAPI spec.
- *
- *
Extensions that enforce authentication (e.g. {@code flash-ext-oidc}) implement
- * this interface and register an instance into {@link OpenApiSecurityRegistry} via the
- * {@link dev.relism.extension.FlashContext}. {@link OpenApiExtension} picks it up
- * at spec-generation time — no coupling between the two extensions at install time.
- *
- *
Multi-tenant: multiple contributors may coexist. For handlers secured by
- * {@code @Authenticated}/{@code @RolesAllowed}, each matching contributor adds its
- * own entry to the operation's {@code security} array (OpenAPI OR semantics).
- */
-public interface OpenApiSecurityContributor {
-
- /**
- * Unique scheme name used as a key in {@code components.securitySchemes}
- * and referenced from each operation's {@code security} array.
- */
- String schemeName();
-
- /**
- * The OpenAPI security scheme definition object placed under
- * {@code components.securitySchemes.}.
- *
- *
- */
- Map schemeDefinition();
-
- /**
- * Returns the scopes/roles required for the given handler class under this scheme,
- * or {@code null} if this contributor does not secure the handler.
- *
- *
- *
{@code null} — handler is not secured by this contributor (skip)
- *
empty list — handler requires authentication, no specific scopes
- *
non-empty list — handler requires these scopes/roles
Created and provided to the {@link dev.relism.extension.FlashContext} by
- * {@link OpenApiExtension} at install time. Other extensions (e.g. {@code flash-ext-oidc})
- * retrieve it via {@code ctx.find(OpenApiSecurityRegistry.class)} and register their
- * contributor — the OpenAPI extension then picks it up lazily at spec-generation time.
- *
- *