Arbitrary query parameter names?
See original GitHub issueI’m pretty new to openapi, so apologies if this has been asked before. I haven’t been able to find a similar question anywhere.
I’m working creating an openapi.yml for an existing API we have at my workplace.
For better or worse, the API supports arbitrary query parameter names. Values are always supplied. These pairs are interpreted as tag name/value pairs of particular resources (computational resources). Here are a few examples (with some name simplifications) of how the API can be invoked:
GET /resources?state=active&tagName1=tagValue1&tagName2=tagValue2
GET /resources?tagName6=tagValue6
GET /resources?state=active
Both the tagNameN
s and tagValueN
’s are user-supplied and arbitrary, but have to conform to be “identifier names” (no spaces, alphanumeric, must not start with a digit).
The only query parameter with a fixed, known name is state
.
Is there some way of expressing this notion in openapi?
I appreciate this is pretty unusual, and perhaps the description might be the only means to express this.
For reference here’s a section of my openapi.yml file for this endpoint.
openapi: 3.0.0
info:
title: Service
description: Endpoints
version: 1.0.0
paths:
/resources:
get:
parameters:
- in: query
name: state
schema:
type: string
enum:
- active
- inactive
- in: query
# TODO - how to describe tagNameN/tagValueN here?
responses:
'200':
description: "All resources successfully obtained."
Any insights or advice appreciated.
Thanks in advance.
Issue Analytics
- State:
- Created 2 years ago
- Comments:8 (5 by maintainers)
Top GitHub Comments
@danieljacobs1 Free-form query parameters can be defined as a single parameter whose value is a dictionary and that uses
style: form
+explode: true
(this is the default serialization style for query parameters). The parametername
can be arbitrary, it does not appear in the URL but may be used by code generators.The name format can be defined in OAS 3.1 using
patternProperties
orpropertyNames
. Make sure to use the^
and$
anchors in regexes because regexes are not implicitly anchored.patternProperties
example:propertyNames
example:OAS 3.0 also supports free-form query parameters, but does not have a way to limit their names.
Sorry for being so very slow getting back on this. @hkosova your screenshot looks exactly like what I was looking for. Thank you! I’ll close this issue. Thanks again.