Aliasing query parameters

[o-felixz]

Consider the query parameter query in the following request: https://my.api/api/endpoint?query=some%20query

I could document this parameter like so:

parameters:
  - name: query
    in: query
    description: Search term
    schema:
      type: string
    required: true

Now, our api supports a short alias for the query parameter, q: https://my.api/api/endpoint?q=some%20query

From my research I am unable to find an explicit example of how to document this properly in OAS 3.0. Is there already a solution to this in the spec that I have missed?

Otherwise I would suggest introducing an aliases keyword for parameters, like so:

parameters:
  - name: query
    aliases:
      - q
    in: query
    description: Search term
    schema:
      type: string
    required: true

I expect the name would be a "primary" alias and that it, together with aliases would form a list, perhaps in descending order of importance if necessary, of mutually exclusive names/aliases for the given parameter.

[MikeRalphson]

Although aliasing parameter names doesn't seem to be common (I could quickly only find one definite example - https://api.open.fec.gov/swagger/ - where the aliased parameters were duplicated) that could be because of the lack of existing support, and duplicating a parameter doesn't help if it should be required: true.

I personally see some value in this for describing existing APIs, though it would add complexity to implementing the specification around detecting duplicate and overriding parameters, as well as path-parameter substitution.

[mschechter-bellese]

This would be very useful for content properties as well. I use Java, and Jackson allows you to create multiple aliases for a field to ensure backward-compatibility when re-working an API.

It would be useful to provide that information at the contract level so that it's not isolated to the implementation side.

[SampsonCrowley]

@MikeRalphson it's definitely less common because of lack of support

[kscheirer]

I am evaluating this as a possible use case for overlays, https://github.com/OAI/Overlay-Specification/discussions/9.

I don't think overlays would be useful here. There is no copy operation in overlays to duplicate a parameter. An overlay could add a second parameter, but as noted this fails when "required" is true.