⬆️ Update ReDoc to version 2.x #9700
Conversation
FastAPI has for the past 4 years been using the the `next` version of ReDoc (development version of 2.0.0). The official 2.0.0 version was however released around 9 months ago and the `next` tag still points to `2.0.0-rc.75`. I thought it would be a good idea to update to the final version now rather than the old release candidate. I also noticed that the examples in the documentation shows what the file used to look like, but the license information has been moved to a separate file and there's just a pointer to that nowadays. I updated the example with what users can today expect to find there now. It's of course a bit of a question if the version should be locked to 2.0.0 or if the `latest` tag should instead be used. Please let me know if you'd rather have me switch to that tag.
934ccb3 to
5c3537b
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Currently passing redoc UI parameters has the following issues: * It puts json-ed values of parameters in single quotes, which will break if the value itself contains single quotes. * If the value is falsy, only the name of the parameter is used. This syntax is *not* treated as falsy by redoc. The latter cases the download button to be always hidden, because the default parameters have "hide-download-button": False. There is no way to un-hide it with the current code. Change this to use the javascript API to pass parameters[1], which is much simpler and more robust. Also, stop using the "next" version of redoc, as suggested here[2]. This was an old release candidate for version 2. Use the officially released version 2. [1] https://redocly.com/docs/redoc/deployment/html/#the-redoc-object [2] fastapi/fastapi#9700
Currently passing redoc UI parameters has the following issues: * It puts json-ed values of parameters in single quotes, which breaks if the value itself contains single quotes. * If the value is falsy, only the name of the parameter is used. This syntax is *not* treated as falsy by redoc. The latter causes the download button to be always hidden, because the default parameters have "hide-download-button": False. There is no way to un-hide it with the current code. Change this to use the javascript API to pass UI parameters[1], which is much simpler and more robust. Also, stop using the "next" version of redoc, as suggested here[2]. This was an old release candidate for version 2. Use the officially released version 2. [1] https://redocly.com/docs/redoc/deployment/html/#the-redoc-object [2] fastapi/fastapi#9700
Currently passing redoc UI parameters has the following issues: * It puts json-ed values of parameters in single quotes, which breaks if the value itself contains single quotes. * If the value is falsy, only the name of the parameter is used. This syntax is *not* treated as falsy by redoc. The latter causes the download button to be always hidden, because the default parameters have "hide-download-button": False. There is no way to un-hide it with the current code. Change this to use the javascript API to pass UI parameters[1], which is much simpler and more robust. Also, stop using the "next" version of redoc, as suggested here[2]. This was an old release candidate for version 2. Use the officially released version 2. [1] https://redocly.com/docs/redoc/deployment/html/#the-redoc-object [2] fastapi/fastapi#9700
This comment was marked as outdated.
This comment was marked as outdated.
There was a problem hiding this comment.
Hi @joakimnordling, thanks for the PR and apologies for the delay in reviewing!
I agree with you that we should update the next tag, at least to 2.0.0 (which is out since September 2022). We could also consider pointing it to a more current version like 2.1.0 or 2.1.5. I'm not sure about latest as that would automatically pull in any new version without any control on our end.
I'm going to ask Tiangolo to chime in on the issue and leave the final decision up to him 🙏
My own suggestion would be to update it to 2.1.5 (assuming there's no issues found with it, which I doubt) and lock it to that version so you have control of when it gets updated. But let's wait for Tiangolo's decision. |
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
|
Any updates on this? At this point the version that FastAPI points to is already 2.5 years old and still an rc. |
I decided to update the PR to use the latest released 2.4.0 version of ReDoc since we've not heard anything back yet. I also noticed there were some new translations added, so updated the texts in them as well (fortunately only code stuff was needed, as I don't know all those languages). A bit of a question of course if we should use `redoc@2.4.0` or just `redoc@2`. If you feel like using the `@2` instead, feel free to update or request me to update.
|
I decided to update the PR to use the latest released 2.4.0 version of ReDoc since we've not heard anything back yet. I also noticed there were some new translations added, so updated the texts in them as well (fortunately only code stuff was needed, as I don't know all those languages). A bit of a question of course if we should use |
|
@ziglef if you want a quick workaround to get the latest ReDoc 2.4.0 and SwaggerUI 5.19.0 and are fine with them being loaded from your servers instead of a CDN, I could mention that I just published version 0.2.0 of fastapi-standalone-docs. And sorry for marketing this in this thread. |
|
Hey @joakimnordling thanks for the ping, we have internally been using the custom version for docs as explained in FastAPI Docs - Custom Docs UI and that has worked for us for now. I do appreciate your efforts into keeping this issue alive for consideration. I personally believe that keeping just the major versions |
|
Hey, any plans on pushing this soon? Are there any blockers? |
There was a problem hiding this comment.
Thanks for updating to 2.4.0 @joakimnordling! This looks good to me.
|
Thank you @joakimnordling! I would go with After that, the only missing step is for one of the team members (e.g. @svlandeg, me) to try this branch locally and ensure nothing obvious is breaking, and then I'll merge it. 🤓 |
Thanks @tiangolo ! I've now updated to Minor note that I could not verify the URL on UNPKG (https://unpkg.com/redoc@2/bundles/redoc.standalone.js, used in the tutorial for using an alternative CDN) actually works because that CDN seems to be down at least for me and based on some comments online it seems to have had some issues for some time now. I don't think it should matter for the concepts shown in the guides, but still preferred to mention this. |
I'll try and do that this week! |
Seems like the UNPKG CDN now works and https://unpkg.com/redoc@2/bundles/redoc.standalone.js does a nice 302 redirect to https://unpkg.com/redoc@2.4.0/bundles/redoc.standalone.js and serves the content. |
FastAPI has for the past 4 years been using the the
nextversion of ReDoc (development version of 2.0.0). The official2.0.0version was however released around 9 months ago and thenexttag still points to2.0.0-rc.75. I thought it would be a good idea to update to the final version now rather than the old release candidate.I also noticed that the examples in the documentation shows what the file used to look like, but the license information has been moved to a separate file and there's just a pointer to that nowadays. I updated the example with what users can today expect to find there now.
It's of course a bit of a question if the version should be locked to
2.0.0or if thelatesttag should instead be used. Please let me know if you'd rather have me switch to that tag.