Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support allowReserved keyword for query parameters #631

Closed
actinium15 opened this issue Dec 22, 2021 · 0 comments · Fixed by #632
Closed

Support allowReserved keyword for query parameters #631

actinium15 opened this issue Dec 22, 2021 · 0 comments · Fixed by #632

Comments

@actinium15
Copy link
Contributor

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant