Forum Discussion

arty13's avatar
New Contributor
3 years ago

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


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 and it's docs, it should work.



  - 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



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



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




2 Replies

  • 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 (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:

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


    We're also looking to address this with a new side-spec called Overlays ( 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.