REDOC – AN OPENAPI-POWERED DOCUMENTATION UI

  August 17, 2016

We all love SwaggerUI. It is one of the reasons Swagger/OpenAPI is so popular. Recently a few new trends have appeared in API documentation world. One of them is three-panel design documentation. The competing API specifications formats have them, e.g. API Blueprint has aglio, Postman has Postman Documenter, etc.

That's why APIs.guru has been developing new reinvented OpenAPI-powered documentation - ReDoc. We do it for our client Rebilly. But it is fully open-source and free!

Check out our demo!

Three-panel design

ReDoc is done in responsive three-panel design:

The left panel contains a scroll-synchronized reference menu. The middle panel contains endpoints/methods documentation. And the right panel contains various samples: request samples, response samples and code samples (via vendor extensions).

Payload documentation

The main ReDoc feature is an ability to document complex request/response payloads:

ReDoc payload doc

As you can see, ReDoc supports nested schemas and displays them in-place with the ability to collapse/expand.

Also, you won't believe, but ReDoc supports discriminator:

ReDoc discriminator

Responses documentation

All method responses are listed under the method definition and are colored according to the response code. Response also contains header and payload documentations:

ReDoc responses

Samples

Payload samples are generated based on the JSON-schema. We have developed OpenAPI-sampler tool which generates meaningful samples. Beyond type and format, it takes advantage of default, enum and example fields from the spec.

As samples may be big, only the first level is expanded by default. You can even copy the full sample to the clipboard using "Copy" button:

Redoc copy

As it was mentioned earlier, ReDoc supports custom code samples via OpenAPI vendor extensions. Check out our docs or sample schema for more details.

Other features

Simple integration

No backend is required. All ReDoc resources (HTML, CSS, JS) are bundled into a single file and are accessible from our CDN. Check out the minimal index.html:

<!DOCTYPE html>

<html>

<head>

<title>API Docs</title>

<!-- needed for mobile devices -->

<meta name="viewport" content="width=device-width, initial-scale=1">

</head>

<body>

<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>

<script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"></script>

</body>

</html>

Introduction section

ReDoc pulls the 1-st level markdown headings from Swagger description and pulls them into reference menu! So you can easily add custom sections to your API docs.

Your brand logo

ReDoc uses x-logo vendor extension to display your brand logo in the docs.

What's next?

We have already started working on the new release. Which new features will be included? It depends on your feedback! Don't hesitate to open issues and feature requests on our GitHub. We are open to your suggestions!

Also, you can hire APIs.guru to assist with ReDoc integration or to develop unique look and feel for your ReDoc-powered documentation.

Don't forget to star our project on GitHub! <3