DEV Community

楊東霖
楊東霖

Posted on • Originally published at devplaybook.cc

Best API Documentation Tools for Developers in 2025 (Swagger, Redoc, Scalar, and More)

#webdev #programming #rest #api

Good API documentation is the difference between developers integrating your API in an afternoon and spending a week emailing you questions. In 2025, the tools available range from dead-simple auto-generated docs to polished documentation platforms that rival Stripe's docs.

This guide covers what actually works.

The OpenAPI Ecosystem

Most API documentation tools are built around OpenAPI (formerly Swagger), a JSON/YAML specification format for describing REST APIs. An OpenAPI spec describes:

  • All available endpoints
  • Request/response schemas with types and examples
  • Authentication methods
  • Error codes and descriptions

Write (or generate) an OpenAPI spec once, and documentation tools render it into interactive documentation automatically.

Swagger UI — The Baseline

Swagger UI is the original OpenAPI renderer. It's what most developers think of when they hear "API docs" — the navy blue panel with expandable endpoints.

How It Works 

# Install in a Node.js project
npm install swagger-ui-express swagger-jsdoc
Enter fullscreen mode Exit fullscreen mode 
// Express.js integration
const swaggerUi = require('swagger-ui-express')
const swaggerDocument = require('./swagger.json')

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument))
Enter fullscreen mode Exit fullscreen mode

Or generate from JSDoc comments:

const swaggerJsdoc = require('swagger-jsdoc')

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],  // Files with JSDoc annotations
}

const spec = swaggerJsdoc(options)

/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
app.get('/users', usersController.getAll)
Enter fullscreen mode Exit fullscreen mode

FastAPI Integration (Python)

FastAPI generates OpenAPI specs automatically from your code:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int, q: str | None = None):
    """
    Get a user by ID.

    - **user_id**: The ID of the user to retrieve
    - **q**: Optional search query
    """
    return {"user_id": user_id, "query": q}
Enter fullscreen mode Exit fullscreen mode

FastAPI serves Swagger UI at /docs and ReDoc at /redoc out of the box.

Swagger UI Pros

  • Universally understood
  • Try-it-out functionality built in
  • Free, open source
  • Works with any OpenAPI spec

Swagger UI Cons

  • Dated visual design
  • Limited customization without significant CSS overrides
  • Cluttered for complex APIs with many endpoints

Redoc — Clean, Three-Panel Layout

Redoc renders OpenAPI specs in a clean three-panel layout: navigation on the left, documentation in the center, code samples on the right. It's significantly better-looking than Swagger UI.

Basic Usage 

<!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">
    <style>
      body { margin: 0; padding: 0; }
    </style>
  </head>
  <body>
    <redoc spec-url='https://api.example.com/openapi.json'></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>
Enter fullscreen mode Exit fullscreen mode

Node.js Integration 

npm install redoc
Enter fullscreen mode Exit fullscreen mode 
const express = require('express')
const { redocHtml } = require('redoc')

app.get('/docs', (req, res) => {
  res.send(redocHtml({
    title: 'My API',
    specUrl: '/openapi.json',
    redocOptions: {
      hideDownloadButton: false,
      disableSearch: false,
    },
  }))
})
Enter fullscreen mode Exit fullscreen mode

Redoc Pro Features

Redoc's paid tier (Redocly) adds:

  • Multiple API versions in one portal
  • Custom theming
  • Private documentation
  • Search across multiple APIs

Redoc Pros

  • Beautiful default design
  • Fast, lightweight
  • Works offline
  • Good mobile experience

Redoc Cons

  • No try-it-out in the free version
  • Less interactive than Swagger UI
  • Paid tier required for advanced features

Scalar — The Modern Alternative

Scalar is the newest serious contender. It combines the clean look of Redoc with the interactivity of Swagger UI, and adds modern features like multiple client code generation.

Key Features

  • Modern design: Clean, customizable, dark mode by default
  • Request client: Built-in API client for testing endpoints (like Swagger UI's try-it-out but better)
  • Code generation: Automatically generates code samples in curl, fetch, Python, Go, PHP, and more
  • Framework integrations: Official packages for Express, Fastify, Hono, and more

Setup with Express 

npm install @scalar/express-api-reference
Enter fullscreen mode Exit fullscreen mode 
import { apiReference } from '@scalar/express-api-reference'

app.use(
  '/reference',
  apiReference({
    spec: {
      url: '/openapi.json',
    },
    theme: 'purple',
  })
)
Enter fullscreen mode Exit fullscreen mode

Setup with Hono 

import { Hono } from 'hono'
import { apiReference } from '@scalar/hono-api-reference'

const app = new Hono()

app.get('/reference', apiReference({
  theme: 'purple',
  spec: { url: '/openapi.json' },
}))
Enter fullscreen mode Exit fullscreen mode

Generated Code Samples

Scalar automatically generates code in multiple languages for each endpoint:

# curl
curl -X GET https://api.example.com/users \
  -H 'Authorization: Bearer TOKEN'

# JavaScript fetch
const response = await fetch('https://api.example.com/users', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer TOKEN',
  },
})

# Python
import httpx

response = httpx.get(
  'https://api.example.com/users',
  headers={'Authorization': 'Bearer TOKEN'}
)
Enter fullscreen mode Exit fullscreen mode

Scalar Pros

  • Best DX of the three (clean + interactive)
  • Multi-language code generation
  • Free and open source
  • Active development (GitHub stars growing fast)
  • Built-in theming

Scalar Cons

  • Newer, smaller community
  • Some framework integrations still maturing

Recommendation: For new projects in 2025, Scalar is worth trying before defaulting to Swagger UI.

Stoplight — API Design-First Platform

Stoplight is a platform for API design, documentation, and mocking. It goes beyond rendering existing specs — it's designed for the API-first workflow where you design the API spec before writing code.

Key Features

  • Visual API editor: Design OpenAPI specs without writing YAML
  • Mock servers: Automatically generate a mock server from your spec
  • Style guide enforcement: Linting rules to ensure API consistency
  • Documentation portal: Host polished docs with custom domains
  • Git sync: Specs live in your repo, Stoplight syncs from them

Use Case 

# openapi.yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
              example:
                users:
                  - id: 1
                    name: Alice
                  - id: 2
                    name: Bob
Enter fullscreen mode Exit fullscreen mode

With Stoplight, this spec is:

  1. Visually editable in their UI
  2. Validated against your style guide
  3. Mockable instantly
  4. Published as hosted documentation

Pricing

  • Free: 1 project, public docs
  • Starter: $39/month for 5 projects
  • Professional: $99/month for unlimited projects

Best For

  • Teams doing API-first design
  • Companies that need hosted documentation with custom domains
  • Teams that want mock servers for frontend development

Mintlify — Documentation Platform

Mintlify is a documentation platform (not specifically API docs) that many developer tools companies use for polished documentation sites. It supports OpenAPI for API reference sections within broader documentation.

What It Is

Mintlify generates a complete documentation site from MDX files and OpenAPI specs. You get:

  • A full docs site (not just API reference)
  • OpenAPI rendering integrated into the docs
  • Custom domain
  • Search
  • Analytics

Setup 

// mint.json
{
  "name": "My Product",
  "openapi": "/api-reference/openapi.json",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    },
    {
      "group": "API Reference",
      "pages": ["api-reference/users", "api-reference/products"]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Pricing: Free for open source; paid plans for private docs starting around $150/month.

Best for: Developer tools companies that want Stripe-level documentation quality.

Generating OpenAPI Specs From Your Code

Node.js/TypeScript with Zod 

npm install zod-to-openapi
Enter fullscreen mode Exit fullscreen mode 
import { z } from 'zod'
import { OpenAPIRegistry, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi'

const registry = new OpenAPIRegistry()

const UserSchema = registry.register(
  'User',
  z.object({
    id: z.string().uuid(),
    name: z.string().min(1),
    email: z.string().email(),
  })
)

registry.registerPath({
  method: 'get',
  path: '/users/{id}',
  summary: 'Get user by ID',
  request: {
    params: z.object({ id: z.string().uuid() }),
  },
  responses: {
    200: {
      description: 'The user',
      content: {
        'application/json': {
          schema: UserSchema,
        },
      },
    },
  },
})

const generator = new OpenApiGeneratorV3(registry.definitions)
const spec = generator.generateDocument({
  openapi: '3.0.0',
  info: { title: 'My API', version: '1' },
})
Enter fullscreen mode Exit fullscreen mode

Quick Recommendation Guide

Need Recommended Tool
Quick self-hosted docs Swagger UI
Clean read-only docs Redoc
Modern interactive docs Scalar
API-first design + mock server Stoplight
Full documentation site Mintlify
Generate spec from TypeScript zod-to-openapi
FastAPI / Django REST Built-in (automatic)

Find free developer tools at DevPlaybook.cc — including tools for JSON formatting, Base64 encoding, and JWT decoding.

Level Up Your Dev Workflow

Found this useful? Explore DevPlaybook — cheat sheets, tool comparisons, and hands-on guides for modern developers.

🛒 Get the DevToolkit Starter Kit on Gumroad — 40+ browser-based dev tools, source code + deployment guide included.

Top comments (0)