📦 @node-lib-tech/swagger-auto-gen-express

Auto-generate and serve Swagger (OpenAPI 3) documentation dynamically from your Express routes.
No manual YAML writing required – just plug it into your Express app and get instant API docs with Swagger UI.

✨ Features

• 🚀 Auto-discovers your Express routes
• 📖 Generates OpenAPI 3.0 docs
• 📝 Exports to a .yaml file for external use
• 🔑 Supports JWT bearer authentication
• 🔌 Works with both require and import
• 🛠️ Configurable: info, servers, tags, components
• ✅ Auto-learns request bodies from first requests
• ✅ Manual request body schemas via bodies option

📦 Installation

npm install @node-lib-tech/swagger-auto-gen-express
# or
yarn add @node-lib-tech/swagger-auto-gen-express

⚡ Quick Usage

With CommonJS (require)

const express = require("express");
const swaggerGenerator = require("@node-lib-tech/swagger-auto-gen-express");

const app = express();

// Example route
app.get("/hello", (req, res) => res.send("Hello World!"));

// Swagger setup
swaggerGenerator({
  app,
  apiName: "/docs",
  BackEndUrl: "http://localhost:3000",
  WEBSITE_URL: "http://localhost:4200",
  info: {
    title: "My API Documentation",
    version: "1.0.0",
    description: "Auto-generated Swagger docs"
  },
  API_Pattern: "/api/v1/",
 // ✅ Add request body schemas manually
  bodies: {
    "/api/user:post": {
      name: { type: "string", example: "Abhishek" },
      role: { type: "string", example: "Developer" },
    },
    "/api/order/{id}:put": {
      status: { type: "string", example: "shipped" },
      amount: { type: "number", example: 2000 },
    },
  },
});

app.listen(3000, () => {
  console.log("✅ Server running at http://localhost:3000");
  console.log("📘 Swagger docs available at http://localhost:3000/docs");
});

With ES Modules (import)

import express from "express";
import swaggerGenerator from "@node-lib-tech/swagger-auto-gen-express";

const app = express();

app.get("/hello", (req, res) => res.send("Hello World!"));

swaggerGenerator({
  app,
  apiName: "/docs",
  BackEndUrl: "http://localhost:3000",
  WEBSITE_URL: "http://localhost:4200",
  info: { title: "My API Docs", version: "1.0.0" },
  API_Pattern: "/api/v1/",
 // ✅ Add request body schemas manually
  bodies: {
    "/api/user:post": {
      name: { type: "string", example: "Abhishek" },
      role: { type: "string", example: "Developer" },
    },
    "/api/order/{id}:put": {
      status: { type: "string", example: "shipped" },
      amount: { type: "number", example: 2000 },
    },
  },
});

app.listen(3000, () => {
  console.log("✅ Server running at http://localhost:3000");
  console.log("📘 Swagger docs available at http://localhost:3000/docs");
});

⚙️ Options

| Option | Type | Default | Description | |------------------|----------|-------------------------------------------|-------------| | app | Express | required | Express app instance | | apiName | string | /docs | Route for Swagger UI | | BackEndUrl | string | required | Backend base URL (Swagger server) | | API_Pattern | string | required | API_Pattern="/api/v1/" (Swagger server) | | envName | string | local | Environment name shown in Swagger servers | | pathName | string | ./swagger-ui-express/swagger.yaml | Path to generated YAML file | | WEBSITE_URL | string | required | Example frontend URL added to headers | | components | object | {} | Extra Swagger components (schemas, params, etc.) | | info | object | { title: "Auto-generated Swagger", version: "1.0.0" } | Swagger info metadata | | swaggerOptions | object | {} | Options passed to Swagger UI | | moreoptions | object | {} | Extra options for swagger-jsdoc | | bodies | object | {} | Manual request body schemas |

🔑 Authentication Example

This library includes JWT Bearer Authentication by default.

• In Swagger UI, click Authorize
• Enter your token as:

Bearer <your_token>

📝 Defining Request Body Schemas

You can define schemas for specific routes using the key format:

<path>:<method>

Example:

bodies: {
  "/api/user:post": {
    name: { type: "string", example: "Abhishek" },
    role: { type: "string", example: "Developer" },
  },
  "/api/order/{id}:put": {
    status: { type: "string", example: "shipped" },
    amount: { type: "number", example: 2000 },
  },
}

• Auto-sampling: If you don’t define a schema, the generator will learn from the first req.body it sees.
• Manual override: If both are present, manual bodies definition takes priority.

🔗 Swagger UI

Start your app and open:
👉 http://localhost:3000/docs

📜 License

MIT © @node-lib-tech