devdocs-auto

Zero-config runtime API documentation for Express.

DevDocs Auto automatically captures live traffic from your Express application and builds accurate, interactive API documentation — no decorators, no YAML, no manual spec writing. Just install, call one function, and your docs are live at /docs.

What It Does

Most API doc tools require you to manually annotate every route or maintain a separate spec file. DevDocs Auto works differently — it sits as middleware on your Express app, captures real request and response traffic as it flows through, and incrementally builds documentation from actual usage.

The result is a Swagger-like interactive UI served directly from your running server that gets more accurate the more traffic your API receives.

Demo

http://localhost:3000/docs        → Interactive UI
http://localhost:3000/docs/spec   → Raw JSON spec

Features

• Zero config — one function call, no decorators, no YAML
• Auto route discovery — scans your Express router stack on startup
• Live traffic capture — builds request/response schemas from real traffic
• Interactive Try It panel — execute any API directly from the docs UI
• All HTTP methods — GET, POST, PUT, PATCH, DELETE
• JSON body support — syntax-highlighted JSON editor with validation
• FormData / Multipart — file upload + mixed field support
• Custom headers — add any key-value header per request
• Auth handling — global token bar auto-fills Authorization header for protected routes
• Path param inputs — validates all :param fields before sending
• Query param support — edit URL directly or use captured query schema
• Middleware chain display — shows middleware names per route
• Sample responses — stores and displays real response samples per status code
• Response schema inference — infers response shape from captured traffic
• Route filtering — filter by method, auth status, or search by path/tag
• Tag grouping — routes grouped by tag in sidebar

Compatibility

Works With

| Environment | Supported | | --------------------------- | --------- | | Express 4.x | ✅ | | Express 5.x | ✅ | | Node.js >= 14 | ✅ | | TypeScript | ✅ | | JavaScript (CommonJS) | ✅ | | MERN stack | ✅ | | Any Express-based framework | ✅ |

Does Not Work With

| Environment | Reason | | ------------------------ | ----------------------------------------- | | Fastify | Not Express — different middleware system | | Koa | Not Express | | NestJS | Uses its own decorator-based routing | | Non-Node.js backends | Node.js only | | Serverless (Lambda/Edge) | No persistent server to mount docs on | | HTTP-only (no Express) | Requires Express app instance |

Minimum Requirements

| Requirement | Version | | ----------- | --------- | | Node.js | >= 14.0.0 | | Express | >= 4.0.0 | | npm | >= 6.0.0 |

No database required. No external services. Docs are generated and served entirely in-memory from your running Express process.

Installation

npm install devdocs-auto

Quick Start

import express from "express";
import { initAutoDoc } from "devdocs-auto";

const app = express();
app.use(express.json());

// Call BEFORE registering your routes
initAutoDoc(app);

// Your routes go here
app.get("/api/health", (req, res) => res.json({ status: "ok" }));
app.post("/api/user/login", (req, res) => res.json({ token: "xyz" }));

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
  // Docs auto-available at http://localhost:3000/docs
});

Important: Call initAutoDoc(app) after app.use(express.json()) but before registering your routes.

JavaScript (CommonJS)

const express = require("express");
const { initAutoDoc } = require("devdocs-auto");

const app = express();
app.use(express.json());

initAutoDoc(app);

// your routes...

app.listen(3000);

Configuration Options

initAutoDoc(app, {
  name: "My API", // Project name shown in the UI header (default: 'My API')
  path: "/docs", // URL path to serve docs (default: '/docs')
  maxSamples: 10, // Max request/response samples stored per route (default: 10)
  enableInProd: false, // Enable in production environment (default: false)
});

Option Details

| Option | Type | Default | Description | | -------------- | --------- | ---------- | --------------------------------------------------------- | | name | string | 'My API' | Project name displayed in the docs UI | | path | string | '/docs' | Base path for docs. UI at {path}, spec at {path}/spec | | maxSamples | number | 10 | Number of real request/response samples stored per route | | enableInProd | boolean | false | By default docs are disabled when NODE_ENV=production |

How It Works

Express App Starts
      ↓
initAutoDoc(app) called
      ↓
Capture middleware installed (intercepts all req/res)
      ↓
setImmediate → Router stack scanned → All routes seeded into store
      ↓
app.listen() called by your app
      ↓
/docs and /docs/spec mounted on same port
      ↓
Real traffic flows → middleware captures body/query/headers/response schemas
      ↓
/docs/spec returns live JSON spec built from store
      ↓
/docs UI fetches spec and renders interactive documentation

UI Features

Sidebar

• All routes listed and grouped by tag
• Filter by HTTP method (GET / POST / PUT / PATCH / DELETE)
• Filter by auth-required routes
• Search by path, method, or tag

Route Detail Panel

• Method badge + full path
• Auth status (🔒 Auth Required / Public)
• Hit counter (how many times route was called)
• Path parameters table with inferred types
• Query parameters schema (after traffic)
• Request body schema (after traffic)
• Captured response schemas per status code (200, 400, 401, 500...)
• Real response samples (togglable)
• Middleware chain display

Try It Panel

Every route has a built-in request executor:

| Feature | Description | | ------------------ | ---------------------------------------------------------------- | | URL editing | Editable URL field — add query params manually | | Path params | Auto-generated inputs for each :param, validated before send | | Authorization | Global token bar — set once, auto-fills all auth routes | | Custom headers | Add any key-value header pair per request | | JSON body | Syntax-highlighted JSON editor with live validation | | FormData | Switch to Form Data mode — add text fields and file uploads | | File upload | Per-field file picker in Form Data mode | | Response panel | Status code, response time, formatted body, response headers tab |

Auth Setup

Set your token once in the Global Token bar at the top of the UI. It is saved to localStorage and automatically applied to all routes where auth: true.

The token is attached as:

Authorization: Bearer <your-token>

If your token already includes Bearer , it won't be duplicated.

Production Usage

By default, docs are disabled in production (NODE_ENV=production). This is intentional — you should not expose internal API structure in production environments.

To enable in production explicitly:

initAutoDoc(app, {
  enableInProd: true,
});

It is strongly recommended to protect the /docs path with authentication middleware if you enable this.

TypeScript Support

DevDocs Auto is written in TypeScript and ships with full type definitions.

import { initAutoDoc, AutoDocOptions } from "devdocs-auto";

const options: AutoDocOptions = {
  name: "FitnEarn API",
  maxSamples: 20,
  path: "/docs",
  enableInProd: false,
};

initAutoDoc(app, options);

Exported API

// Primary function
initAutoDoc(app: Express, options?: AutoDocOptions): void

// Alias for backwards compatibility
autoDoc(app: Express, options?: AutoDocOptions): void

// Types
interface AutoDocOptions {
  name?: string
  path?: string
  maxSamples?: number
  enableInProd?: boolean
}

Endpoints Served

| Endpoint | Description | | ---------------- | ------------------------------------------ | | GET /docs | Interactive documentation UI (HTML) | | GET /docs/spec | Live JSON spec built from captured traffic |

Both endpoints are served on the same port as your Express application. No separate server is started.

Common Issues

Docs show "UI file not found"

Your dist/server/ui/index.html was not copied during build. Run:

npm run build

Make sure your build script copies the UI file:

"build": "tsc && cpx \"src/server/ui/**/*\" dist/server/ui"

Routes not showing in sidebar

initAutoDoc(app) was called after routes were registered. Move it to before your route registration:

initAutoDoc(app); // ← before routes
app.use("/api", router); // ← routes after

Body/query schema shows empty

Routes show empty schemas until they receive real traffic. Send at least one request to the endpoint and refresh the docs.

CORS error in Try It panel

Add your docs origin to your CORS config:

app.use(
  cors({
    origin: ["http://localhost:3000"], // your server origin
  }),
);

Docs not available in production

Set enableInProd: true in options. See Production Usage.

Example With Route Tags and Auth Middleware

DevDocs Auto reads Express middleware names to display the middleware chain. Named functions produce better docs than anonymous arrows.

// Named middleware — shows as "authenticateToken" in docs
function authenticateToken(req, res, next) {
  const token = req.header("Authorization")?.split(" ")[1];
  if (!token) return res.status(401).json({ message: "Unauthorized" });
  next();
}

// Named controller — shows as "createStudio" in docs
function createStudio(req, res) {
  res.status(201).json({ success: true });
}

router.post("/api/admin/studio", authenticateToken, createStudio);

Anonymous arrow functions will appear as anonymous in the middleware chain and are filtered out of the display.

Security Considerations

• Docs are disabled by default in production
• No authentication is applied to /docs by default — add your own middleware if needed
• The spec endpoint (/docs/spec) exposes route structure, middleware names, and sample request/response data — do not expose publicly without protection
• Global tokens are stored in browser localStorage — only use in trusted environments

License

MIT