swagger openapi custom parameters in the request

Question

There is a path in api with an arbitrary number of optional parameters of approximately this kind:

/orders/123/get-payment-link/provider?customerId=123&amount=2000&custom1=custom1&custom2=custom2...

The api description looks something like this:

paths:
  /orders/{orderId}/get-payment-link/{providerName}:
    get:
      operationId: order_get_payment_link
      tags:
        - /orders
      parameters:
        ...
        - name: customerId
          in: query
          required: true
          example: 123
          schema:
            type: string
        - name: amount
          in: query
          required: true
          example: 2000
          schema:
            type: string
        ...

I can’t understand how can I describe arbitrary optional parameters of type custom, which can be any number and which can be called anything?

Does this answer your question? -- How to document dynamic query parameter names in OpenAPI — Helen
– Helen, Commented Jul 3, 2020 at 13:21

Phil Sturgeon · Accepted Answer · 2020-07-03 12:40:57Z

1

I honestly don't think you can do this. I double checked the specification and I don't see a way of having custom names.

JSON Schema allows this with keywords like patternProperties but that doesn't fit into a Parameter Object!

Hunting for issues on the spec GitHub I did find this issue, which helps if you are using foo[custom1]=a&foo[custom2]=b

      - in: query
        name: filter
        required: false
        schema:
          type: object
          additionalProperties: true
          example:
            foo: bar
            inputs.datetime.gte: 242839744
        style: deepObject

        # The example translates to:
        # ?filter[foo]=bar&filter[inputs.datetime.gte]=242839744

As for arbitrary top level query parameters? There's no way. At least not in v3.0 or v3.1.

answered Jul 3, 2020 at 12:40

Phil Sturgeon

30.8k12 gold badges82 silver badges118 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

swagger openapi custom parameters in the request

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related