Skip to content

Support allowReserved keyword for query parameters #631

@actinium15

Description

@actinium15

OpenAPI 3.1 [0] (and 3.0 as well [1]) notes:

Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.

The way I understand it, it means when allowReserved is set to true for any given query parameter, any , that appear in the value are sent as-is (i.e., without percent-encoding). RapiDoc doesn't seem to honor it currently.

As an example, consider the API definition at [2]. If I were to place this definition in https://editor.swagger.io/ and 'try', the request URI (as seen on Browser DevTools' Network panel) is:

https://example.com/my/api?c=100,100,200,200

However, if I remove/comment-out allowReserved: true for query param c (or set allowReserved: false) this is what the request URI becomes:

https://example.com/my/api?c=100%2C100%2C200%2C200

This is not how RapiDoc behaves, though (there's no special handling for allowReserved in [3] as far as I can tell).

The reason might be due to api-request.js [3] relying on URLSearchParams to build the URI. URLSearchParams assumes form-urlencoded input [4] and encodes all reserved characters.
Since [3] uses it directly, there's no room to honor allowReserved attribute in the current impl.

NB: Quoting from the section 3.4 (Query) of RFC 3986:

   The query component is indicated by the first question
   mark ("?") character and terminated by a number sign ("#") character
   or by the end of the URI.
      query       = *( pchar / "/" / "?" )

Then, in Appendix A:

   pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
   query         = *( pchar / "/" / "?" )
...
   sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
                 / "*" / "+" / "," / ";" / "="

The way I'm reading it, it is allowed for sub-delims to appear non-percent-encoded in the query part of the URI. Setting allowReserved property on a query-parameter in the API definition should prevent its percent-encoding the HTTP request created by RapiDoc.

[0] https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-10 (search for allowReserved)
[1] https://swagger.io/docs/specification/serialization/ (search for allowReserved)
[2]

openapi: 3.0.3
info:
  title: test
  version: 0.0.1
servers:
  - url: 'https://example.com'
components:
  schemas:
    CommaSeparatedQueryParam:
      type: string
      pattern: '(\d+,\d+,\d+,\d+)'
      example: 100,100,200,200
paths:
  /my/api:
    get:
      summary: test api
      operationId: my/test/api
      parameters:
        - in: query
          name: c
          description: comma-separated list of four numbers
          allowReserved: true
          schema:
            $ref: '#/components/schemas/CommaSeparatedQueryParam'
      responses:
        '200':
          description: OK
          content:
            image/*: # Media type
              schema: 
                type: string
                format: binary

[3] https://github.com/mrin9/RapiDoc/blob/master/src/components/api-request.js
[4]

URLSearchParams object uses the application/x-www-form-urlencoded format underneath... URLSearchParams objects will percent-encode anything in the application/x-www-form-urlencoded percent-encode set, and will encode U+0020 SPACE as U+002B (+).

(from https://url.spec.whatwg.org/#example-constructing-urlsearchparams)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions