OpenAPI - manage GET/POST endpoints shared parameters

[orhazal]

Hello @felixguendling,

Following our discussion in #1547 , i tested OpenAPI native way to share one definition (GET with a style: form, explode: true object parameter + POST body with a $ref to the same schema). It validates, but hey-api breaks : types get nested under the wrapper name, objects are serialized as deepObject regardless of the declared style, and array properties throw. So it breaks the ts client.

I see two options :

1. generator-verified sharing: openapi.yml keeps the normal GET parameters: list (ts client unaffected) + the body schema. openapi-cpp gains x-query-params: true on a schema (generated struct gets the query-parsing next to its JSON support making one C++ type for GET and POST) and x-params: on the GET (emits using params = ; and fails generation if list and schema drift). Applied to OneToManyParams first, this immediately surfaces existing drift (missing 11 vehicle* params), so POST silently uses defaults today. Cost: schemas that enable this gain constructors, so designated initializers ({.one = ...}) no longer compile for them ; a few motis test rewrites, and external C++ users of these structs would get the same.
2. the refresh-itinerary pattern: POST /plan keeps routing params as query parameters (same generated plan_params as GET, nothing duplicated) and the body carries only the offset lists. No generator changes.

[orhazal]

I was wondering if it'ss a known hey-api issue, and LLM found these :

• Objects in query params are not being exploded hey-api/hey-api#3437
• Query parameter serialization styles hey-api/hey-api#393
• how should be specified and represent a nested array of a query parameter ? OAI/OpenAPI-Specification#3052

I'm still trying to get a hold of it but it seems that the OpenAPI spec is missing how to manage a nested array parameter.

[felixguendling]

I guess we could just use YAML anchors then?

[orhazal]

Anchors will remove the duplication but will not prevent schema drift between POST and GET versions of an endpoint (e.g. OneToMany POST missing 11 params from GET).

We can use anchors for the parameters shared by the two versions of OneToMany and fix the drift without duplication.
However, nothing will prevent future schema drifts, hence why a solution like option 1 (based on OpenAPI vendor extensions) is interesting.

[traines-source]

I haven't though this through, but maybe it could make things easier if even for the post endpoint we stick with the URL params for all the normal options and just transmit the offsets in the post body?

[felixguendling]

sounds like it's worth a try

[orhazal]

Here is the PR for it : #1558
Feedback appreciated, thank you !

[orhazal]

First tests are looking good :)

With an injected payload :

{

"toOffsets": [

    {"stopId": "fr-sncf_StopArea:OCE87276691", "duration": 2340},

    {"stopId": "fr-sncf_StopArea:OCE87271593", "duration": 4380},

    {"stopId": "fr-sncf_StopArea:OCE87276741", "duration": 420},

    {"stopId": "fr-sncf_StopArea:OCE87276006", "duration": 5280},

]

}

[orhazal]

Should i delete the radius param with this "replacing" it?

[felixguendling]

I would keep the radius as it might be useful for quick evaluations without OSM data.

I will try to find some time to look into your PR.