I have a
filter parameter for an endpoint, here is how it is defined:
/products: displayName: Products get: displayName: List products queryParameters: filter[<field>]: type: string required: false description: | A `field=value` pair defining the filter applied to the response. examples: first: value: ['filter[color]=Black'] description: "Lookup for products with color black." second: value: ['filter[color]=Black','filter[color]=White'] description: "Lookup for products with color black or white." ...
My issue with this is that it does not seem right to mention the parameter name again in the example.
In a simpler situation we would have:
get: displayName: Get product queryParameters: product_id: required: true description: | The identifier of the product. type: string example: ['111','123']
This is nice, and I can generate HTML output something like
So is there a way to use the specs properly to represent a filter that can be used on any field name and exemplify this?
Thanks for your insight.