Description
I'm submitting a...
- Regression
- Bug report
- Feature request
- Documentation issue or request (new chapter/page)
- Support request => Please do not submit support request here, instead post your question on Stack Overflow.
Current behavior
In the techniques - versioning documentation, there's a callout that says:
NOTICE
Selecting the highest matching version based on the array returned from extractor > does not reliably work with the Express adapter due to design limitations. A single version (either a string or array of 1 element) works just fine in Express. Fastify correctly supports both highest matching version selection and single version selection.
This is not actionable, so as a reader of the documentation I don't know what to do about it.
I have looked in the git-blame of the docs, and saw that it's connected to this issue:
Here there's more details, which aren't explained in the documentation:
Known bug here - if there are multiple versions supported across separate
handlers/controllers, we can’t select the highest matching handler.
Since this code is evaluated per-handler, then we can’t see if the highest
specified version exists in a different handler.
if a caller specified several different versions that it accepts, then the Express adapter cannot reliably select the highest matching version because it’s not properly aware all the supported versions at this point in the code.
Expected behavior
The documentation should provide a recommendation for how to work around the issue with versioning when combined with express adapter.
Minimal reproduction of the problem with instructions
What is the motivation / use case for changing the behavior?
Improving the documentation.
Environment
For Tooling issues:
- Node version: whatever
- Platform: docs website