profile
viewpoint

Ask questionsArbitrary query parameter names?

I'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 tagNameNs 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.

OAI/OpenAPI-Specification

Answer questions danieljacobs1

Thanks for the fast reply. I think I saw those earlier when I was searching around, but I wasn't sure.

It would be nice for confirmation, but I read https://github.com/OAI/OpenAPI-Specification/issues/1637 as if they have an endpoint that can produce the query parameter names and would it be possible to generate a UI dynamically from its response.

And https://github.com/OAI/OpenAPI-Specification/issues/1054 has the q as it's query parameter name and it feels a bit different.

For the case I'm asking about, I was imagining it might look like this:

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
          metaVarName: tagName  # Mutually exclusive with 'name'
            schema:
              type: string
              regexp: [_a-zA-Z][_a-zA-Z0-9]*
          metaVarValue: tagValue
            schema:
              type: string
              regexp: [_a-zA-Z][_a-zA-Z0-9]*
      responses:
        '200':
          description: "All resources successfully obtained."

and it could generate a UI that allowed adding of arbitrary numbers of name/value pairs for tags.

It might be possible that one solution in openapi solves all three of the problems, but I'm not qualified to say.

useful!
source:https://uonfu.com/
Github User Rank List