npm package: @node-lib-tech/swagger-auto-gen-express
Description: Auto-generate Swagger (OpenAPI 3.0) docs for Express apps with runtime req.body detection and manual schemas.
Author: Abhishek kumar Singh
Latest version: 1.0.21

# 📦 @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

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

---

## ⚡ Quick Usage

### With CommonJS (`require`)

```js
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`)

```js
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:

```js
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](http://localhost:3000/docs)

---

## 📜 License

[MIT](./LICENSE) © @node-lib-tech