API Documentation (Redoc) for Web Application
Redoc is an OpenAPI renderer with a three-panel layout: navigation on the left, description in the center, and request/response examples on the right. Unlike Swagger UI, Redoc does not provide an interactive "Try it out" form, but it generates readable public documentation even for large APIs with hundreds of endpoints.
Embedding Redoc
The simplest approach is static HTML with CDN:
<!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 production, download the bundle and serve locally. CDN creates external network dependency.
Self-hosted via npm
npm install redoc
Integration with Next.js (static route /docs):
// 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,
}}
/>
);
}
Configuration via x-tagGroups
Redoc supports tag grouping through OpenAPI extension, displaying them as sections in the left menu:
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`
Tag descriptions support full Markdown — you can add diagrams, tables, links.
x-codeSamples — Code Examples in Multiple Languages
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');
Redoc displays a language switcher in the right panel.
Generating openapi.json in Laravel
// routes/api.php — endpoint returns the specification
Route::get('/openapi.json', function () {
return response()->json(
\Dedoc\Scramble\Scramble::getDefaultDocumentGenerator()->generate()
);
})->middleware('throttle:60,1');
Alternative — export static file in CI:
php artisan scramble:export --output=public/openapi.json
Redoc CLI for Static Generation
npx @redocly/cli build-docs openapi.yaml --output docs/index.html
The resulting index.html (~3 MB with inline bundle) deploys to any static hosting (S3, GitHub Pages, Cloudflare Pages). Does not require a server.
Redoc vs Swagger UI — When to Choose
| Criterion | Redoc | Swagger UI |
|---|---|---|
| Visual Quality | High | Medium |
| "Try it Out" Browser | No (view only) | Yes |
| Bundle Size | ~2.5 MB | ~1.5 MB |
| Tag Grouping | x-tagGroups | No |
| x-codeSamples Support | Yes | No |
| Integration into Next.js/React | npm package | npm package |
Optimal strategy: public documentation with Redoc, internal sandbox for developers with Swagger UI on a separate route /api/swagger.
Timeline
Setting up Redoc with custom theme, tag grouping, and code examples: 0.5–1 day. CI integration (auto-export openapi.json, deployment to Cloudflare Pages): 1 additional day.