Parameter encoding

allowReserved

OpenAPI 3.x supports an allowReserved setting for query parameters (only). The effect is to allow reserved characters :/?#[]@!$&'()*+,;= to appear unencoded in request URLs.

OpenAPI 3.x does not support an allowedReserved setting for path parameters but there are occasions when API owners want to model this. One example is a URL with a path parameter item: https://stuff.com/store/{item}. The API may be designed so that {item} could be most-popular or book/most-popular where the / character should be rendered without encoding (giving https://stuff.com/store/book/most-popular).

Speakeasy supports an OpenAPI extension x-speakeasy-param-encoding-override: allowReserved which when set on a path parameter renders the URL without encoding these reserved characters :/?#[]@!$&'()*+,;=.

Here’s the above-mentioned example with the path parameter encoding extension in use.

  /store/{item}:
    get:
      operationId: item
      parameters:
        - name: item
          in: path
          schema:
            type: string
            example: most-popular
          required: true
          x-speakeasy-param-encoding-override: allowReserved
      responses:
        "200":
          ...

As of November 2024, x-speakeasy-param-encoding-override is supported for Java. Let us know if you need support in another language.