[
https://issues.apache.org/jira/browse/CAMEL-24125?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-24125:
--------------------------------
Description:
When using Camel JBang in dev mode, the dev consoles are available at /q/dev/
endpoints. Currently, to discover the available parameters, types, enums, and
defaults for each console, you need to look at the source code.
Since we now support POST (JSON body) on dev console endpoints, and we already
have rich generated metadata for every console (parameter name, type, enum
values, default value, required flag, description), we can expose this as an
OpenAPI specification at /q/dev/api.
The approach:
- Add a new /q/dev/api endpoint in ManagementHttpServer that generates an
OpenAPI 3.0 spec
- For each registered dev console, generate:
- POST /q/dev/{id} with a JSON request body schema from the console metadata
- The index listing GET /q/dev
- Type mapping from console metadata: string, integer, boolean, enum constraints
- The spec is dynamic - reflects whichever consoles are actually loaded at
runtime (including component-specific ones like Kafka, OpenTelemetry, etc.)
- Console metadata is already available at runtime via
CatalogCamelContext.getDevConsoleParameterJsonSchema()
This would make the dev console API self-documenting and allow tools, IDEs, and
AI agents to discover and use the API without reading source code.
h3. Design decisions
- *POST only* - The OpenAPI spec documents only POST endpoints with JSON
request body. GET with query parameters still works for human use (curl,
browser) but is not part of the formal API contract. POST is the better
contract for programmatic use: typed values (booleans, integers) stay typed
instead of everything being a string in query params, and it is easier for
tools and AI agents to construct.
- *Input contract only* - The spec defines the input contract (request body
schema) for each console using the existing generated metadata. This includes
parameter names, types, enum constraints, default values, required flags, and
descriptions.
- *No response schema* - Console responses are built dynamically in
doCallJson() with arbitrary structure, nested arrays, and dynamic content that
varies based on runtime state. The spec declares application/json as response
content type without a detailed schema. The input contract is the valuable part.
- *JSON responses only* - The OpenAPI spec only documents JSON responses
(application/json). Text-based responses are a human convenience not documented
in the spec.
was:
When using Camel JBang in dev mode, the dev consoles are available at /q/dev/
endpoints. Currently, to discover the available parameters, types, enums, and
defaults for each console, you need to look at the source code.
Since we now support POST (JSON body) on dev console endpoints, and we already
have rich generated metadata for every console (parameter name, type, enum
values, default value, required flag, description), we can expose this as an
OpenAPI specification at /q/dev/api.
The approach:
- Add a new /q/dev/api endpoint in ManagementHttpServer that generates an
OpenAPI 3.0 spec
- For each registered dev console, generate:
- GET /q/dev/{id} with query parameters from the console metadata
- POST /q/dev/{id} with a JSON request body schema from the same parameters
- The index listing GET /q/dev
- Type mapping from console metadata: string, integer, boolean, enum constraints
- The spec is dynamic - reflects whichever consoles are actually loaded at
runtime (including component-specific ones like Kafka, OpenTelemetry, etc.)
- Console metadata is already available at runtime via
CatalogCamelContext.getDevConsoleParameterJsonSchema()
This would make the dev console API self-documenting and allow tools, IDEs, and
AI agents to discover and use the API without reading source code.
> camel-console - Expose dev console API contract via OpenAPI spec at /q/dev/api
> ------------------------------------------------------------------------------
>
> Key: CAMEL-24125
> URL: https://issues.apache.org/jira/browse/CAMEL-24125
> Project: Camel
> Issue Type: Improvement
> Components: camel-jbang
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Major
> Fix For: 4.22.0
>
>
> When using Camel JBang in dev mode, the dev consoles are available at /q/dev/
> endpoints. Currently, to discover the available parameters, types, enums, and
> defaults for each console, you need to look at the source code.
> Since we now support POST (JSON body) on dev console endpoints, and we
> already have rich generated metadata for every console (parameter name, type,
> enum values, default value, required flag, description), we can expose this
> as an OpenAPI specification at /q/dev/api.
> The approach:
> - Add a new /q/dev/api endpoint in ManagementHttpServer that generates an
> OpenAPI 3.0 spec
> - For each registered dev console, generate:
> - POST /q/dev/{id} with a JSON request body schema from the console metadata
> - The index listing GET /q/dev
> - Type mapping from console metadata: string, integer, boolean, enum
> constraints
> - The spec is dynamic - reflects whichever consoles are actually loaded at
> runtime (including component-specific ones like Kafka, OpenTelemetry, etc.)
> - Console metadata is already available at runtime via
> CatalogCamelContext.getDevConsoleParameterJsonSchema()
> This would make the dev console API self-documenting and allow tools, IDEs,
> and AI agents to discover and use the API without reading source code.
> h3. Design decisions
> - *POST only* - The OpenAPI spec documents only POST endpoints with JSON
> request body. GET with query parameters still works for human use (curl,
> browser) but is not part of the formal API contract. POST is the better
> contract for programmatic use: typed values (booleans, integers) stay typed
> instead of everything being a string in query params, and it is easier for
> tools and AI agents to construct.
> - *Input contract only* - The spec defines the input contract (request body
> schema) for each console using the existing generated metadata. This includes
> parameter names, types, enum constraints, default values, required flags, and
> descriptions.
> - *No response schema* - Console responses are built dynamically in
> doCallJson() with arbitrary structure, nested arrays, and dynamic content
> that varies based on runtime state. The spec declares application/json as
> response content type without a detailed schema. The input contract is the
> valuable part.
> - *JSON responses only* - The OpenAPI spec only documents JSON responses
> (application/json). Text-based responses are a human convenience not
> documented in the spec.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
