[jira] [Commented] (CAMEL-24118) camel-openapi-java: RestOpenApiReader emits invalid OpenAPI 3.x (formData params, collectionFormat styles, boolean/primitive-array/header types, 3.1 type loss) - umbrella

["Claus Ibsen (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/CAMEL-24118?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18096798#comment-18096798 ] 

Claus Ibsen commented on CAMEL-24118:
-------------------------------------

Fixed via https://github.com/apache/camel/pull/24784

> 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
>            Assignee: Claus Ibsen
>            Priority: Major
>              Labels: code-review
>             Fix For: 4.22.0
>
>
> 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)