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 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?
Solved! Go to Solution.
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.
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: