Swagme

About

Node Js CLI tool that auto generates swagger api documentation for express web and nextjs servers. Takes advantage of the MVC Pattern. Supports Mongoose, Prisma, and Drizzle database schemas.

Quick Start

This will interactively create swag.config.json, swagger.json and swagger.yml based on your project.

npx swagme

For Usage Instructions

npx swagme --help

Installation

npm install -g swagme

Prerequisites

Required Dependencies

Your project must have Express installed:

npm install express

Recommended Dependencies

For displaying Swagger documentation:

npm install swagger-ui-express yaml

Database Support (Optional)

Swagme can auto-generate schemas from your database models:

• Mongoose: npm install mongoose
• Prisma: npm install @prisma/client
• Drizzle: npm install drizzle-orm

CLI Commands

Default Command

Run the full interactive setup (configure + build):

swagme

This will:

• Create a swag.config.json configuration file
• Scan your Express routes and database schemas
• Generate swagger.json and swagger.yml files
• Create a docs folder with route and schema definitions

npx swagme run

Run the full workflow with options for customization.

Usage:

npx swagme run [directory] [options]

Arguments:

• [directory] - Working directory of the project (default: current directory)

Options:

• -y, --auto - Auto configure and build without prompts
• -c, --config - Only configure (create config file)
• -b, --build - Only build swagger files
• -r, --routes - Update routes (default: true)
• -s, --schemas - Update schemas (default: true)
• --scan - Scan project files for routes and schemas
• --json - Build only swagger.json file
• --yaml - Build only swagger.yml file

Examples:

# Interactive setup in current directory
npx swagme run

# Auto-configure without prompts
npx swagme run -y

# Build only, skip configuration
npx swagme run -b

# Scan project and build both JSON and YAML
npx swagme run --scan --json --yaml

# Build only JSON file
npx swagme run -b --json

# Build only YAML file
npx swagme run -b --yaml

# Run in specific directory
npx swagme run /path/to/project -y

npx swagme config

Generate only the configuration file without building documentation.

Usage:

npx swagme config [options]

Options:

• -y, --auto - Auto configure without prompts
• -p, --dir - Project directory/folder (default: current directory)

Examples:

# Interactive configuration
npx swagme config

# Auto-configure without prompts
npx swagme config -y

# Configure specific directory
npx swagme config -p /path/to/project

npx swagme build

Build swagger documentation files from existing configuration.

Usage:

npx swagme build [options]

Options:

• -p, --dir - Project directory/folder (default: current directory)
• --json - Build only swagger.json file
• --yaml - Build only swagger.yml file
• -r, --routes - Update routes (default: true)
• -s, --schemas - Update schemas (default: true)
• --scan - Scan project files for routes and schemas

Examples:

# Build with existing config
npx swagme build

# Build and scan project files
npx swagme build --scan

# Build only JSON
npx swagme build --json

# Build only YAML
npx swagme build --yaml

# Build without updating routes
npx swagme build --no-routes

# Build without updating schemas
npx swagme build --no-schemas

npx swagme del

Remove all swagme configuration files and folders.

Usage:

npx swagme del [options]

Options:

• -p, --dir - Project directory/folder (default: current directory)
• -y, --auto - Auto delete all swagme files and folders without confirmation prompt (default: false)

Examples:

# Delete swagme files from current directory (with confirmation prompt)
npx swagme del

# Auto-delete without confirmation prompt
npx swagme del -y

# Delete from specific directory
npx swagme del -p /path/to/project

# Auto-delete from specific directory without prompt
npx swagme del -p /path/to/project -y

Configuration File

The swag.config.json file stores your project settings:

{
  "name": "My API",
  "version": "1.0.0",
  "description": "API Documentation",
  "routes": "src/routes",
  "schema": "src/models",
  "docs": "docs",
  "main": "src/app.js",
  "database": "mongoose",
  "authorization": "bearer",
  "gitignore": true
}

Configuration Options:

• name - API name
• version - API version
• description - API description
• routes - Path to routes folder
• schema - Path to database models/schemas folder
• docs - Output folder for generated documentation
• main - Main Express application file
• database - Database type (mongoose, prisma, or drizzle)
• authorization - Authorization type (e.g., bearer)
• gitignore - Whether to add docs folder to .gitignore

Swagger UI Setup

Express.js Setup

const express = require('express');
const app = express();
const fs = require('fs');
const path = require('path');
const SwaggerUI = require('swagger-ui-express');
const YAML = require('yaml');

// Load swagger documentation
const swaggerdocs = YAML.parse(
  fs.readFileSync(path.join(__dirname, 'swagger.yml'), 'utf-8')
);
// Or use JSON: const swaggerdocs = require('./swagger.json');

// Swagger documentation endpoint
app.use('/api/docs', SwaggerUI.serve, SwaggerUI.setup(swaggerdocs));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Swagger docs at http://localhost:3000/api/docs');
});

Workflow Examples

First Time Setup

# 1. Install swagme globally
npm install -g swagme

# 2. Navigate to your Express project
cd my-express-project

# 3. Run interactive setup
npx swagme

# 4. Follow the prompts to configure your project

Daily Development Workflow

# After making changes to routes or schemas, rebuild documentation
npx swagme build --scan

CI/CD Integration

# Auto-build documentation without prompts
npx swagme run -y --scan

Features

✅ Auto-detect Express routes - Scans your route files automatically
✅ Database schema support - Works with Mongoose, Prisma, and Drizzle
✅ Multiple output formats - Generate JSON and/or YAML
✅ Interactive CLI - User-friendly prompts for configuration
✅ Auto mode - Skip prompts for CI/CD pipelines
✅ Gitignore integration - Optionally add docs to .gitignore
✅ Authorization support - Configure API authorization schemes

Troubleshooting

Express dependency not found

npm install express

Swagger UI Express not found

npm install swagger-ui-express

Support

Support (from Malawi or USA)

License

MIT License - See LICENSE file for details

Links

• GitHub: M2KDevelopments/swagme
• NPM: swagme
• Issues: Report a bug