ReDoc — Reinventing OpenAPI-powered Documentation

SwaggerUI proves the possibility to use OpenAPI specs as a single source for generating API documentation. Although we love SwaggerUI we should admit an obvious fact: SwaggerUI is rather an API console than an API documentation.

A long time ago in a galaxy far, far away….

Rebilly adopted Swagger as a definition language for their API, and they were looking for a documentation engine. But they wanted to go beyond the industry standards and document their API to the fullest. Here’s how they did it:

• every field in JSON payloads;
• in their quest, they had to use almost every OpenAPI feature including lots of Mr. discriminator ;)
• resulting spec is really huge: 12K+ lines and growing! (one of the biggest we’ve seen in the wild). And believe us — they use all the possible tricks to reduce duplications.

So, they approached us with this challenging project: to build a brand new documentation engine — ReDoc.

Check out demo!

The best part?

Together with Rebilly we realized the full potential of ReDoc since other API owners face exactly same problems. That’s why we’ve decided to open-source it and stick with vanilla OpenAPI. We’d love to thank Rebilly and personally Adam Altman for sponsoring this open-source project! After months of work now we feel confident to make 1.0.0 release.

Why should I use ReDoc?

Let’s take a look!

Extremely easy deployment

No, it’s really easy. Don’t believe us? Take a look at the minimal setup:

That’s all folks! We’ve bundled everything (html, css, javascript) into a single file! Also, we’re serving the latest release (and all previous releases) from our CDN.

Why else?

• It’s free and open-source project under MIT license
• The widest OpenAPI features support (yes, it supports even discriminator)
• Neat documentation for nested objects
• Meaningful request/response samples generated using openapi-sampler
• Code samples support (via vendor extension)
• Responsive three-panel design with menu/scrolling synchronization
• Integrate API introduction into side menu — ReDoc takes advantage of markdown headings from OpenAPI description field. It pulls them into side menu and also supports deep linking.

Roadmap

Currently, we have the following global key points on our TO-DO list:

• Docs pre-rendering (performance and SEO)
• Built-in API Console
• Support for external styling

What’s next? It depends on you! Don’t hesitate to open issues and feature requests on GitHub. PRs are welcome too :)

Moreover, you can hire APIs.guru to do integration or customization of ReDoc for you needs.

Stay tuned

At the beginning of the next week, we will release a support tool which will help you to easily setup OpenAPI spec repository with lots of appetizing features.

If you need any help with integration ReDoc feel free to ask! Subscribe to our twitter so as not to miss ReDoc new releases and other news. Will you try ReDoc? Tell us in comments bellow :)

Originally published at apis.guru on July 28, 2016.