[
https://issues.apache.org/jira/browse/CAMEL-24564?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-24564:
--------------------------------
Description:
ApiDevConsole (core/camel-console) already generates an OpenAPI 3.0 spec for
the /q/dev/* dev console endpoints, but only live, from a running CamelContext
(CAMEL-24514, https://github.com/apache/camel/pull/25883).
CAMEL-24514 added a "readOnly" flag to the @DevConsole annotation and to each
console's generated catalog metadata
(src/generated/resources/META-INF/org/apache/camel/dev-console/<id>.json)
specifically so this classification (GET vs POST) is available statically at
build time, not just at runtime.
This ticket is to build on that: add a build-time/tooling step that aggregates
the per-module dev-console/*.json catalog metadata across the whole build into
one consolidated static OpenAPI document (e.g. openapi.json), and publish it as
part of the camel-catalog, so tools can discover the dev console API surface
(paths, verbs, parameters) ahead of time without needing a running CamelContext
instance.
h3. Where the static generator should run
catalog/camel-catalog already aggregates every module's dev-console/<id>.json
verbatim today, via PrepareCatalogMojo in
tooling/maven/camel-package-maven-plugin (the same mojo family CAMEL-24514
touched for the readOnly field). The static OpenAPI generator should run there
too, reading the same aggregated JSON files directly — no CamelContext required.
h3. Shared logic extraction (design decided, not yet implemented)
ApiDevConsole.buildOpenApi()'s path/operation-building logic
(buildPathItem/buildConsoleParameters/buildConsoleRequestBody) is pure JSON
transformation over a console's id/displayName/description/readOnly + its
parsed "options" JsonObject — it has no CamelContext dependency already. To
avoid duplicating it between the live console and the static generator, extract
it into a shared class.
Constraint: core/camel-console depends on camel-support/camel-core;
tooling/maven/camel-package-maven-plugin deliberately avoids those and only
depends on camel-util-json, camel-tooling-model, camel-tooling-util,
spi-annotations (to keep the plugin lightweight and independent of the Camel
version being built). The only viable shared home reachable by both is
tooling/camel-tooling-model (which already holds
DevConsoleModel/DevConsoleOptionModel) or camel-util-json (generic JSON parser,
wrong cohesion for domain logic).
Decision: add a new class in tooling/camel-tooling-model, e.g.
DevConsoleOpenApiHelper, with static methods mirroring today's private
ApiDevConsole methods (buildPathItem/buildParameters/buildRequestBody),
operating on plain JsonObject/JsonArray (not the typed model beans, to match
how ApiDevConsole already parses raw JSON today and minimize churn).
core/camel-console would need to add camel-tooling-model as a new dependency —
precedented already by core/camel-core-catalog, which depends on
camel-tooling-model for the same kind of catalog-consumption reason.
- ApiDevConsole calls the shared helper with data sourced live from
DevConsoleRegistry.
- The static generator (in PrepareCatalogMojo or a sibling mojo) calls the same
helper with data read directly from the aggregated catalog dev-console/*.json
files.
Blocked on: PR #25883 (CAMEL-24514) merging to main first — this work should be
based on top of it, not developed in parallel.
was:
ApiDevConsole (core/camel-console) already generates an OpenAPI 3.0 spec for
the /q/dev/* dev console endpoints, but only live, from a running CamelContext
(CAMEL-24514, https://github.com/apache/camel/pull/25883).
CAMEL-24514 added a "readOnly" flag to the @DevConsole annotation and to each
console's generated catalog metadata
(src/generated/resources/META-INF/org/apache/camel/dev-console/<id>.json)
specifically so this classification (GET vs POST) is available statically at
build time, not just at runtime.
This ticket is to build on that: add a build-time/tooling step (likely in
tooling/camel-package-maven-plugin and/or the catalog module) that aggregates
the per-module dev-console/*.json catalog metadata across the whole build into
one consolidated static OpenAPI document (e.g. openapi.json), and publish it as
part of the camel-catalog, so tools can discover the dev console API surface
(paths, verbs, parameters) ahead of time without needing a running CamelContext
instance.
Suggested approach:
- Reuse the path/operation-building logic already in
ApiDevConsole.buildOpenApi() (or extract it into a shared helper) so the static
generator and the live /q/dev/api console stay consistent.
- Aggregate across all catalog/*.json + component dev-console/*.json resources
at catalog-build time (similar to how other catalog artifacts such as
components.properties / data formats are aggregated today).
- Store the generated spec in catalog/camel-catalog (or a dedicated location)
and expose it via CamelCatalog similar to other catalog lookups.
Related: CAMEL-24514 / PR #25883 (readOnly metadata), and PR #25884 (chore:
removed an unrelated stale dev-console catalog entry found while regenerating
metadata for this work).
> camel-console: Generate a static OpenAPI spec for all dev consoles and
> publish it in the camel-catalog
> ------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-24564
> URL: https://issues.apache.org/jira/browse/CAMEL-24564
> Project: Camel
> Issue Type: New Feature
> Components: camel-core
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Major
> Fix For: 4.23.0
>
>
> ApiDevConsole (core/camel-console) already generates an OpenAPI 3.0 spec for
> the /q/dev/* dev console endpoints, but only live, from a running
> CamelContext (CAMEL-24514, https://github.com/apache/camel/pull/25883).
> CAMEL-24514 added a "readOnly" flag to the @DevConsole annotation and to each
> console's generated catalog metadata
> (src/generated/resources/META-INF/org/apache/camel/dev-console/<id>.json)
> specifically so this classification (GET vs POST) is available statically at
> build time, not just at runtime.
> This ticket is to build on that: add a build-time/tooling step that
> aggregates the per-module dev-console/*.json catalog metadata across the
> whole build into one consolidated static OpenAPI document (e.g.
> openapi.json), and publish it as part of the camel-catalog, so tools can
> discover the dev console API surface (paths, verbs, parameters) ahead of time
> without needing a running CamelContext instance.
> h3. Where the static generator should run
> catalog/camel-catalog already aggregates every module's dev-console/<id>.json
> verbatim today, via PrepareCatalogMojo in
> tooling/maven/camel-package-maven-plugin (the same mojo family CAMEL-24514
> touched for the readOnly field). The static OpenAPI generator should run
> there too, reading the same aggregated JSON files directly — no CamelContext
> required.
> h3. Shared logic extraction (design decided, not yet implemented)
> ApiDevConsole.buildOpenApi()'s path/operation-building logic
> (buildPathItem/buildConsoleParameters/buildConsoleRequestBody) is pure JSON
> transformation over a console's id/displayName/description/readOnly + its
> parsed "options" JsonObject — it has no CamelContext dependency already. To
> avoid duplicating it between the live console and the static generator,
> extract it into a shared class.
> Constraint: core/camel-console depends on camel-support/camel-core;
> tooling/maven/camel-package-maven-plugin deliberately avoids those and only
> depends on camel-util-json, camel-tooling-model, camel-tooling-util,
> spi-annotations (to keep the plugin lightweight and independent of the Camel
> version being built). The only viable shared home reachable by both is
> tooling/camel-tooling-model (which already holds
> DevConsoleModel/DevConsoleOptionModel) or camel-util-json (generic JSON
> parser, wrong cohesion for domain logic).
> Decision: add a new class in tooling/camel-tooling-model, e.g.
> DevConsoleOpenApiHelper, with static methods mirroring today's private
> ApiDevConsole methods (buildPathItem/buildParameters/buildRequestBody),
> operating on plain JsonObject/JsonArray (not the typed model beans, to match
> how ApiDevConsole already parses raw JSON today and minimize churn).
> core/camel-console would need to add camel-tooling-model as a new dependency
> — precedented already by core/camel-core-catalog, which depends on
> camel-tooling-model for the same kind of catalog-consumption reason.
> - ApiDevConsole calls the shared helper with data sourced live from
> DevConsoleRegistry.
> - The static generator (in PrepareCatalogMojo or a sibling mojo) calls the
> same helper with data read directly from the aggregated catalog
> dev-console/*.json files.
> Blocked on: PR #25883 (CAMEL-24514) merging to main first — this work should
> be based on top of it, not developed in parallel.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
