[
https://issues.apache.org/jira/browse/CAMEL-24125?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18097319#comment-18097319
]
Claus Ibsen commented on CAMEL-24125:
-------------------------------------
Merged via PR https://github.com/apache/camel/pull/24894
> 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)
