Federico Mariani created CAMEL-24118:
----------------------------------------
Summary: camel-openapi-java: RestOpenApiReader emits invalid
OpenAPI 3.x (formData params, collectionFormat styles,
boolean/primitive-array/header types, 3.1 type loss) - umbrella
Key: CAMEL-24118
URL: https://issues.apache.org/jira/browse/CAMEL-24118
Project: Camel
Issue Type: Bug
Components: camel-openapi-java
Affects Versions: 4.21.0
Reporter: Federico Mariani
Umbrella for a family of related defects in {{RestOpenApiReader}} where the
generated document is invalid OpenAPI 3.x or semantically wrong. All were
empirically confirmed by generating documents end-to-end from REST DSL on
current main (both 3.0 and 3.1 output). Most predate the swagger-core migration
(e2ad230d86fc, CAMEL-18963) and were faithfully ported from the apicurio-era
code (793bce17d12a, CAMEL-12619); none are pinned by tests.
h3. 1. formData params emitted as in: formData (illegal in OAS 3.x) -
RestOpenApiReader.java:548-562, 641-642
{{param.getType().name()}} is used verbatim as {{Parameter.in}}; only {{body}}
is diverted to {{requestBody}}. {{RestParamType.formData}} emits
{{"in":"formData"}} - not a legal value ({{query|header|path|cookie}}). Fix:
map formData params to a {{requestBody}} with
{{application/x-www-form-urlencoded}} (or {{multipart/form-data}} per consumes)
object schema.
h3. 2. collectionFormat -> style mapping wrong -
RestOpenApiReader.java:613-615, 713-728
{{multi}} -> {{deepObject}} (deepObject is for object-valued params; clients
serialize arrays wrongly). {{csv}} -> {{form}} without {{explode: false}}, so
csv params silently get exploded (multi) semantics. Fix: csv ->
form+explode=false; multi -> form+explode=true; ssv/tsv -> spaceDelimited;
pipes -> pipeDelimited.
h3. 3. boolean in/out type emits type: number, format: boolean -
RestOpenApiReader.java:998-999
{{.outType("boolean")}} -> {{{"type":"number","format":"boolean"}}}. Should be
{{BooleanSchema}}.
h3. 4. Primitive-array types (int[], string[], long[], ...) emit items: {} -
RestOpenApiReader.java:1007-1015
When {{array && ref == null}} the computed primitive schema is discarded:
{{.outType("int[]")}} -> {{{"type":"array","items":{}}}}. Model-class arrays
work (ref != null). CAMEL-21076 fixed the neighboring [] double-strip but not
this.
h3. 5. Response headers typed long/float/double emit invalid types -
RestOpenApiReader.java:862-866, 914-922
Only {{int}} -> {{integer}} is mapped; header {{dataType("long")}} ->
{{{"schema":{"type":"long"}}}} - not a JSON Schema type. Fix: long ->
integer/int64, float/double -> number/float|double (also in the array-items
branch).
h3. 6. Array response headers lose the array wrapper -
RestOpenApiReader.java:867-886, 909-912
{{.header("X-Codes").dataType("array").arrayType("string")}} -> header schema
{{{"type":"string"}}} instead of {{{"type":"array","items":{"type":"string"}}}}.
h3. 7. 3.1 output silently drops type from raw new Schema().type(...) helpers -
RestOpenApiReader.java:909-912, 917-919, 983-986
The 3.1 serializer emits {{types}}, not {{type}}. Parameter schemas handle this
({{addType}} guarded by {{SpecVersion.V31}}) but response-header schemas and
the byte[] special case only call {{setType}}: with {{version=3.1}} a header
schema emits {{{}}} and {{outType("byte[]")}} emits {{{"format":"byte"}}} with
no type - silent 3.0/3.1 divergence. Introduced when 3.1 support was added
(779ab53d27b3/b2b757ba0b4d).
h3. Root cause / fix direction
The reader builds schemas through several duplicated ad-hoc paths (params,
response headers, body types) each with its own partial type-mapping table.
Suggest one shared "DSL type -> swagger schema" mapping utility using typed
schema classes (which set both {{type}} and {{types}}), used by all paths, plus
a golden-file test validating generated documents against the official OpenAPI
meta-schema (would have caught this whole family).
----
_This issue was researched and filed by Claude Code on behalf of [~croway]
(GitHub: Croway), as part of a deep code review of camel-rest-openapi and
camel-openapi-java on main (4.22.0-SNAPSHOT). Full findings document available
on request._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
