🚀 swagger-auto-doc

Zero-Config Swagger/OpenAPI Generator for All Node.js Frameworks (TS / JS / CJS)

swagger-auto-doc automatically generates Swagger/OpenAPI documentation for your Node.js APIs — no YAML, decorators, or manual JSDoc. It captures runtime requests and responses and builds beautiful, real-time documentation for Express, Fastify, Koa, Hapi, and NestJS — working with CommonJS, ESM, and TypeScript.

📦 Installation

npm install swagger-auto-doc

or with yarn:

yarn add swagger-auto-doc

⚡ Supported Frameworks

| Framework | Status | Integration Type | | -------------- | ----------------- | --------------------------------- | | Express.js | ✅ Fully Supported | Middleware | | Fastify | ✅ Fully Supported | Hook (onSend) | | Koa.js | ✅ Supported | Async Middleware | | Hapi.js | ✅ Supported | Lifecycle Extension | | NestJS | ✅ Supported | Works via Express/Fastify Adapter |

🔧 Module Usage

swagger-auto-doc works with CommonJS, ES Modules, and TypeScript.

🧱 CommonJS (CJS)

// index.js
const express = require('express');
const { init } = require('swagger-auto-doc');

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

app.get('/ping', (req, res) => res.json({ pong: true }));

init(app);

app.listen(3000, () => console.log('🚀 Docs: http://localhost:3000/api-docs'));

🧩 ECMAScript Modules (ESM)

// index.mjs
import express from 'express';
import { init } from 'swagger-auto-doc';

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

app.post('/login', (req, res) => res.json({ user: req.body.username }));

init(app);
app.listen(3000);

🧠 TypeScript (TS)

// main.ts
import express from 'express';
import { init } from 'swagger-auto-doc';

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

app.get('/status', (req, res) => res.json({ ok: true }));

init(app);
app.listen(3000);

Works seamlessly in TypeScript with full type hints. Enable "esModuleInterop": true in your tsconfig.json.

🧭 Framework Integration Examples

Express.js

const express = require('express');
const { init } = require('swagger-auto-doc');

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

app.get('/users', (req, res) => res.json([{ id: 1, name: 'John' }]));
init(app);
app.listen(3000);

Fastify

import fastify from 'fastify';
import { init } from 'swagger-auto-doc';

const app = fastify();
app.post('/data', async (req, reply) => ({ received: req.body }));

init(app);
app.listen({ port: 3000 });

Koa.js

import Koa from 'koa';
import Router from '@koa/router';
import { init } from 'swagger-auto-doc';

const app = new Koa();
const router = new Router();

router.get('/hello', ctx => { ctx.body = { message: 'Hi from Koa!' }; });

app.use(router.routes());
init(app);
app.listen(3000);

Hapi.js

import Hapi from '@hapi/hapi';
import { init } from 'swagger-auto-doc';

const server = Hapi.server({ port: 3000 });
server.route({ method: 'GET', path: '/check', handler: () => ({ ok: true }) });

init(server);
await server.start();

NestJS

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { init } from 'swagger-auto-doc';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  init(app.getHttpAdapter().getInstance());
  await app.listen(3000);
}
bootstrap();

✅ Works for both Express and Fastify-based Nest apps.

📄 Generated Endpoints

| Endpoint | Description | | --------------- | --------------------------------- | | /api-docs | Interactive Swagger UI | | /openapi.json | Machine-readable OpenAPI 3.0 Spec |

Example JSON:

{
  "openapi": "3.0.0",
  "info": { "title": "My API", "version": "1.0.0" },
  "paths": {
    "/ping": {
      "get": {
        "summary": "Auto-generated GET /ping",
        "responses": {
          "200": { "description": "Auto-captured response" }
        }
      }
    }
  }
}

⚙️ Options

You can customize the Swagger behavior:

init(app, {
  pathDocs: '/docs',         // Custom Swagger UI route
  pathJson: '/openapi-spec', // Custom JSON route
  title: 'My API Docs',
  version: '1.0.1',
  description: 'Auto-generated Swagger docs from runtime data.',
  sampleLimit: 25            // Max captured samples per route
});

🧰 Advanced Usage

Export OpenAPI Spec to File

import { getSpec } from 'swagger-auto-doc';
import fs from 'fs';

fs.writeFileSync('openapi-snapshot.json', JSON.stringify(getSpec(), null, 2));

Disable in Production

if (process.env.NODE_ENV !== 'production') {
  init(app);
}

Merge with Custom OpenAPI Spec

const baseSpec = require('./manual-openapi.json');
const final = { ...baseSpec, ...getSpec() };

🧩 Auto Framework Detection

| Framework | Detection Logic | | --------- | ------------------------------------ | | Express | app._router | | Fastify | app.addHook | | Koa | app.context | | Hapi | app.ext | | NestJS | app.getHttpAdapter().getInstance() |

❤️ Contributing

Contributions and suggestions are always welcome! If you'd like to extend support to more frameworks (Adonis, Sails, etc.), open a PR or issue.

📜 License

MIT © 2025 Sayyed Mohammad Adil Built for developers who love automation, clarity, and zero boilerplate.