OpenApi 3 specify all Query Parameters using a single Schema ref with Marshmallow Plugin

[arty13]

Hi,

I have a python project and I am using Marshmallow to define my schemas for input, output and query parameters.

I am now trying to create my OpenAPI 3 docs using apispec library and I'm running into an issue with rendering my query parameters.

I have this snippet in my doc declaration of my route where ListQueryParameters contains all my query parameters (like page, sortby, etc..) It fails to render unless I add `name`.

But according to https://apispec.readthedocs.io/en/latest/_modules/apispec/ext/marshmallow/schema_resolver.html#Schem... and it's docs https://apispec.readthedocs.io/en/latest/api_ext.html#apispec.ext.marshmallow.schema_resolver.Schema..., it should work.

 parameters:
  - customerId
  - in: query
    name: queryParams
    schema: $ref: '#/components/schemas/ListQueryParameters'

In the final generation of my openapi spec documentation the query param section it shows queryParams as a JSON object for input which has all my listed parameters.

However I want the final docs generated to be a name value pair of these properties, not a nested object.

I can manually specify these as a workaround, but don't want to maintain this list of properties as some apis have 50+ query parameters

 parameters:
- customerId
- in: query
  name: sortby
  description: Sort by description
- in: query
  name: page
  description: Current Page to view
  schema:
    type: int
...

 
Is there an easy way to resolve accomplish this without doing my workaround?

Thanks,

Art

[ponelat]

Hi @arty13 

I'm not familiar with the Marshmellow enough to comment on that side, but for the OpenAPI side it sounds like you're after a groups of $refs which isn't support in OpenAPI yet (unfortunately, I think it's an important feature too). You can track the spec issue here https://github.com/OAI/OpenAPI-Specification/issues/445 (it's old, but you can ping to get it to the attention of the OpenAPI spec team which meets weekly).

Not many workarounds exist.

You could write a script to inject a bunch of $refs, something that would create the following:

parameters:
- $ref: '#/components/parameters/One'
- $ref: '#/components/parameters/Two'
- $ref: '#/components/parameters/N'
# etc...
components:
  parameters:
    One: 
      name: one
      in: query
      schema:
        type: string
# etc...

We're also looking to address this with a new side-spec called Overlays (https://github.com/OAI/Overlay-Specification/) which would be a standard way of defining mutations to a base definition.

At this rate there may be a way of doing this with Marshmellow (to inject all those parameters), perhaps reach out to the Marshmellow team and/or GitHub issues there? Feel free to link to this issue if it helps.

[arty13 · Accepted solution]

It was an issue on my side as I did not need to specify the `ref` part pointing to my schema.

Details can be found here:

https://github.com/marshmallow-code/apispec/issues/732