fix: Don't URI encode schema keys when using $ref

[LucianBuzzo]

This fixes an isssue where using $ in type names leads to invalid OpenAPI specs. This would happen because the refName property that is used as the object key for refs and to create $ref attributes is URI encoded on creation, when it only needs to be URI encoded when used in a $ref attribute.

Fixes #1461

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Have you written unit tests?
• Have you written unit tests that cover the negative cases (i.e.: if bad data is submitted, does the library respond properly)?
• This PR is associated with an existing issue?

Test plan

I had a hard time configuring a unit test to check this behaviour, if anyone can provide some guidance on how to do it please let me know, as the test cases in this repo are hard to follow.

[github-actions]

Hello there LucianBuzzo 👋

Thank you and congrats 🎉 for opening your first PR on this project.✨

We will review the following PR soon! 👀

[WoH]

Does this only affect the OpenAPI v2 generator? I think we should be consistent and also adapt the OpenAPI v3 Spec Generator.

[WoH]

That said, I think #1469 would also address this.

I'm not sure if you can URI Encode the ref value, but use the unencoded name as the components/definition key, is that specified somewhere?

[LucianBuzzo]

@WoH I updated my PR to also fix the problem for the v3 generator. AFAICT, what happens is that when the $ref value is resolved, it decodes the URI, resulting in %24 being decoded to $ - however, because we use the encoded value as a key, it can't find it. The resolution lookup would be for $variable, but what's in the schema is %24variable.
By only URI encoding the $ref value, we avoid this particular issue, without resorting to special case escaping of the keys.
URI encoding only the $ref URI value is the canonically correct approach as far as I can see!

[WoH]

LGTM

[amrbahaa360]

Is the PR merged to version 5.1.1?
The issue still exists and has not been solved.

[LucianBuzzo]

@amrbahaa360 It looks like v5.1.1 was released in February, which won't include this change. A new version needs to be released. @WoH would you be able to cut a new version that includes this fix? v5.1.2 perhaps?

[WoH]

https://github.com/lukeautry/tsoa/releases/tag/v6.0.0-rc.4

[LucianBuzzo]

Awesome thanks @WoH !