-
Notifications
You must be signed in to change notification settings - Fork 315
Description
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 aninvalue ofquery. The default value isfalse.
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)