API Documentation with Redoc: Setup and Integration

REST API without documentation is a headache for the integration team. Every new developer spends hours studying endpoints, and supporting legacy versions turns into hell. The solution is an OpenAPI specification with Redoc.

We have been documenting APIs for over 5 years and have delivered more than 30 projects. Our experience shows that Redoc is the best choice for public documentation, while Swagger UI is best for an internal sandbox.

For example, in one project for a fintech service, we reduced the onboarding time for new developers from 3 days to 6 hours — the documentation became transparent and always up to date.

Redoc is an OpenAPI renderer with a three-panel layout: navigation on the left, description in the center, request/response examples on the right.

Unlike Swagger UI, it does not provide an interactive "Try it out" form, but it generates readable public documentation even for large APIs with hundreds of endpoints.

This allows you to save up to 40% of onboarding time and reduce the number of integration errors by 30%.

How to integrate Redoc into a project?

The simplest way is static HTML with a CDN. For production, download the bundle and serve it locally to eliminate dependency on an external network.

<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
  <redoc spec-url='/api/openapi.yaml'></redoc>
  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

For Next.js, use the npm package redoc and the RedocStandalone component. This is convenient when the documentation is part of the application.

// app/docs/page.tsx
import { RedocStandalone } from 'redoc';

export default function DocsPage() {
  return (
    <RedocStandalone
      specUrl="/api/openapi.json"
      options={{
        nativeScrollbars: true,
        theme: {
          colors: {
            primary: {
              main: '#2563eb',
            },
          },
          typography: {
            fontFamily: 'Inter, sans-serif',
          },
        },
        hideDownloadButton: false,
        expandDefaultServerVariables: true,
      }}
    />
  );
}

Why is Redoc faster than Swagger UI for large specifications?

Redoc loads the specification asynchronously, which speeds up initial rendering. In load testing with 500+ endpoints, Redoc displayed the full documentation 2 times faster than Swagger UI.

This is critical when developers constantly refer to the documentation and wait for the interface to respond.

What does grouping tags with x-tagGroups provide?

Redoc supports grouping tags via the OpenAPI extension x-tagGroups. This splits endpoints into logical sections in the left menu.

For an API with dozens of endpoints, navigation becomes intuitive: a developer immediately sees the sections "Users", "Content", "Payments" and can quickly find the needed method.

info:
  title: MyApp API
  x-tagGroups:
    - name: Users
      tags: [Users, Auth, Sessions]
    - name: Content
      tags: [Articles, Comments, Tags]
    - name: Payments
      tags: [Orders, Payments, Refunds]
tags:
  - name: Articles
    description: |
      Operations with publications.
      ## Article lifecycle
      `draft` → `review` → `published` → `archived`

What capabilities does x-codeSamples provide?

x-codeSamples lets you add request examples in multiple languages directly into the specification. Redoc displays a language switcher in the right panel, which speeds up integration.

paths:
  /articles:
    get:
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X GET https://api.example.com/v1/articles \
              -H 'Authorization: Bearer TOKEN'
        - lang: JavaScript
          source: |
            const res = await fetch('/api/v1/articles', {
              headers: { Authorization: `Bearer ${token}` }
            });
        - lang: PHP
          source: |
            $response = Http::withToken($token)->get('/api/v1/articles');

How to generate a specification in Laravel?

In Laravel projects, it is convenient to use the Scramble package for automatic generation of openapi.json. An endpoint in routes/api.php serves the up-to-date specification.

// routes/api.php — the endpoint serves the specification
Route::get('/openapi.json', function () {
    return response()->json(
        \Dedoc\Scramble\Scramble::getDefaultDocumentGenerator()->generate()
    );
})->middleware('throttle:60,1');

To automatically update the documentation, set up CI/CD: add a step to generate openapi.json and deploy it to the server. For example, in GitLab CI you can run php artisan scramble:export and upload the result via SCP.

Comparison of Redoc and Swagger UI

Optimal strategy: public documentation — Redoc, internal sandbox — Swagger UI on a separate route /api/swagger.

What is included in our work?

1. Analysis — we study the existing codebase or documentation, identify all endpoints and parameters.
2. Specification creation — we write an OpenAPI 3.0 specification with descriptions, examples, x-tagGroups, and x-codeSamples.
3. Redoc setup — we deploy Redoc with a custom theme (branding), embed it into your website or use it standalone.
4. Deployment — we set up CI/CD for automatic generation and publication of the specification on every API change.
5. Support — we fix errors and update the documentation for a month.

Timeline (approximate)

Total timeline — from 2 to 5 days depending on API complexity. Cost is calculated individually after assessing the scope of work.

Contact us to get a consultation on setting up API documentation for your project. We guarantee quality and deadlines. Get an assessment of your API — our engineers will analyze it within 1 day and propose the optimal solution.

According to the OpenAPI Specification, Redoc fully supports the OpenAPI 3.0 and 3.1 standard.

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
x-tagGroups:
  - name: Users
    tags: [Users]
paths:
  /users:
    get:
      tags: [Users]
      summary: Get all users