Support static HTML/JS/CSS generation from spec via npm tooling

[alex-sherwin]

It would be great to be able to take any Open API spec and generate a set of static HTML/CSS/JS output (same as what is dynamically rendered by ReDoc currently)

I don't really understand the current trend of ONLY supporting dynamically rendered documentation tools... It would be really nice to be able to automate static HTML/CSS/JS docs at build time so they could be bundled up and deployed to a standard web server. This would greatly ease managing docs for lots of internal projects, offline distribution to clients, offline viewing, etc.

[RomanHotsiy]

related to #62

[erlend-sh]

Seems to me like getting the best of both worlds would be quite doable with a "dynamic static site generator" like @KyleAMathews' https://github.com/gatsbyjs/gatsby. Being built on top of an existing project like that would also mean you could focus primarily on solving API documentation problems, and spend less time solving "rendering stuff on a page" problems.

I've not seen many such projects for Angular though, so making this happen would probably require a major rewrite. In other words, not likely to happen :P Just wanted to float the idea.

[KyleAMathews]

Would be happy to help with this! It'd be a great fit for Gatsby. Gatsby 1.0 will have theme support plus be able to generate sites very easily straight from the specs.

gatsbyjs/gatsby#419

[RomanHotsiy]

Hey @erlend-sh. Thanks for the idea 👍
We will definitely evaluate it.

But this definitely won't happen in the near feature. As we are moving to more interactivity and I'm not sure we can get enough flexibility with gatsby (thanks @KyleAMathews for offering help) or similar tools. E.g. recently we've added search, and are going to implement API Console for ReDoc.

[KyleAMathews]

Cool! Best of luck with things.

FWIW, Gatsby would easily be able to do search, an API console, etc. as sites are built using React components so frontend interactive bits are trivial.

[ranjapri]

Hi Roman,
I also have similar requirements. I want to generate and deploy only static html pages . Is there any way to achieve this?

Thanks & Regards.

[RomanHotsiy]

To clarify: ReDoc is not server-side tool. You can just deploy it to any static web-server and with and will work.
ReDoc is dynamic only in terms of the client browser as it requires spec to work and builds the doc on the fly.
There is no plan to support fully static behaviour. At least in the nearest future.

[ranjapri]

Thanks Roman for the reply,

I understand that if we want to deploy API documentation, we deploy redoc build engine with the required JS and swagger files and after that we start redoc (npm start) which renders the API documentation.

Is there any way to pre generate the required files and deploy only the generated files (not the ReDoc build engine) . To be more precise, is there any way to render the API without deploying the ReDoc build engine.

By looking at your reply it seems there is no way and the ReDoc build engine is required to render the swagger in client browsers. Could you please confirm it.

Thanks & Regards

[RomanHotsiy]

You don't have to start redoc with npm start. You don't need npm, node, nothing!

All you need is to just deploy html page to the server. Here is the example of simplest html page:
https://github.com/Rebilly/ReDoc#tldr

[RomanHotsiy]

Closing as out of scope

[braco]

@KyleAMathews what would we need to do to make this Gatsby-compatible?

It looks like the best this package does is to bundle itself and the spec into one endpoint, but a truly static API doc generator based in React would be amazing and widely adopted, I think.

[RomanHotsiy]

@braco in fact, it is already Gatsby-compatible.

static API doc generator based in React would be amazing and widely adopted

We think so and we are working on this. Stay tuned 😉!

Also see: redoc-cli

[braco]

Hey @RomanGotsiy! Thanks for the reply. You're saying we can expect a true static output sometime... soon? Cool! Thanks for all your work.

[xypnox]

I had the same problem with React Static. Redoc's sidebar in React version of Redoc didn't work when embedded in react static.

There were several ways to solve this issue, One of them was to create the documentation pages separately and not include them in the routes rather, locate them in public folder.

This works but you loose your navbar and other styling.

Another method, which I am using currently is to embed a static page with redoc script and container as an iframe. It does have it's own disadvantages, for example, the scrolling could be janky. But it suited my usecase.

[courtneyaschwartz]

@xypnox Can you elaborate on "didn't work"? What were the symptoms? (Working w/ inegrations here, too.)

FWIW Our chief issue has been the size of our API. When client-side rendered all on a single page, it's a big performance issue. But that's not exactly "because it's React and we need static HTML." Lighthouse complains about the number of HTML nodes. Crashed browsers. Would've happened even with a static HTML page.

So we actually needed output chunked into multiple smaller pages. We've been looking at https://redocpro.redoc.ly/ to solve that. No iframe was needed. No Gatsby either.

[xypnox]

In the beginning I thought the trouble was with redoc's inability to generate static pages. However I found the problem in this thread: #433 (comment)

The problem is with smooth scrolling.

This should be a part of FAQ where it should be mentioned that scrolling doesn't work with smooth scrolling turned on using css.

Or are there future plans to mitigate this?