Forum Discussion

arty13's avatar
arty13
New Contributor
3 years ago
Solved

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

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#SchemaResolver.resolve_parameters and it's docs https://apispec.readthedocs.io/en/latest/api_ext.html#apispec.ext.marshmallow.schema_resolver.SchemaResolver.resolve_parameters, 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

Swagger Core

2 Replies

Sort By
  • ponelat's avatar
    ponelat
    Staff
    3 years ago

    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.