search

outmoded / lout

API documentation generator
Other
276 stars 49 forks source link

encodeUri handlebars helper #179

Closed danieladams456 closed 6 years ago

danieladams456 commented 6 years ago

I am having an issue when deploying my Hapi API on AWS Lambda with lout documentation. API Gateway doesn't like the characters { and } in the documentation link for a route that has path parameters.

Here is the link to the RFC.

Other characters are unsafe because gateways and other transport agents are known to sometimes modify such characters. These characters are "{", "}", "|", "\", "^", "~", "[", "]", and "`".

An example docs link that is currently generated would be the following: /docs?path=/one/{paramTwo}/three/{paramFour}/five#GET

I took a shot at adding a Handlebars helper for URL encoding that link.

Marsup commented 6 years ago

Is it related to lambda specifically ? Because the demo is on AWS and there's no such problem (eg. http://lout.herokuapp.com/docs?path=/path/{pparam}/test#GET).

danieladams456 commented 6 years ago

If I test the lambda from the API Gateway console, it works fine. It seems like the problem is between Cloudfront and API Gateway. Each request is getting a unique Cloudfront request ID header, so I'm pretty sure it's making it to AWS, but the lambda never gets executed. I turned on debug access logging on API Gateway and it never sees those requests. I have a ticket open with AWS trying to confirm it is an issue.

danieladams456 commented 6 years ago

After going back and forth a couple times with support, we confirmed that API Gateway doesn't allow curly braces in URLs.

They are going to update the known issues page to include it. Currently it just says:

The plain text pipe character (|) is not supported for any request URL query string and must be URL-encoded.

I know it makes the URLs not quite as human readable after click, but the link as shown to the user can still be in the original form. One interesting thing to note is this Github issue page also URL encoded the curly braces. If you view the source, it shows the following:

<p>Is it related to lambda specifically ? Because the demo is on AWS and there's no such problem (eg. <a href="http://lout.herokuapp.com/docs?path=/path/%7Bpparam%7D/test#GET" rel="nofollow">http://lout.herokuapp.com/docs?path=/path/{pparam}/test#GET</a>).</p>
danieladams456 commented 6 years ago

I installed the latest version and it works great now on Lambda. Thanks @Marsup!