redoc-cli: Generate HTML *with* dependencies

[DanH42]

First off, I recognize and appreciate the use of being able to generate a single dependency-less HTML file that contains all your documentation. What I'm suggesting is a feature to compliment that functionality, not replace it.

I'm really glad to see redoc-cli bundle has been introduced as an alternative to client-side rendering. As an extreme example, Discord's client-side docs take about 50 seconds to load for me, and that number drops to about 5 seconds with prerendering. For smaller API specs, the page load is nearly instant.
However, the generated HTML file still has some low-hanging fruit for optimization. Rendering with --cdn=true helps, but there are still a number of resources that could be referenced as external files to better leverage caching in both the browser and on the server. In a production environment, the convenience and portability of a zero-dependency HTML file isn't really a factor, and improving page performance takes priority.

Right off the bat, I noticed that the original spec is included as a massive inline base64 blob for downloading. Continuing with Discourse as an example, their minified JSON spec weighs in at around 300k. If this is gzipped to be sent to the browser on its own, it compresses down to about 43k. But with the bundled version, it is instead base64'd, causing it to balloon to 400k. Even if you then gzip the resulting HTML, that base64 still takes up ~71k (base64 text doesn't compress as well as the original spec). All of this is ignoring the fact that, unless the user actually wants to download the spec, it doesn't need to be included in the page at all.

Less critical -- but still desirable -- would be the ability to reference all the other non-HTML assets as external resources as well. This essentially just means the putting style rules at the top of the page in a .css file, and putting the initial declaration of __redoc_state in its own .js file. This would allow those files to be cached by a user's browser, which is nice for documentation that is likely to be accessed frequently by the same user.

Further down the road, this could also potentially enable a scenario where CSS could be generated to be shared between multiple pages documenting different APIs. It looks like the generated CSS isn't always the same right now, but that would be great for a site that hosts documentation for multiple APIs.

[RomanHotsiy]

Thanks for the detailed write-up. That makes lots of sense.

PR's are welcome

[lornajane]

While redoc-cli has been deprecated in favour of Redocly CLI, I think the points here are relevant to Redoc, and we should keep this open for consideration for now