node-api-document

node-api-document

Generate Beautiful API Documentation for Node.js Applications

• 🌐 Live Documentation
• 📦 NPM Package
• 🐛 Report Bug
• 💡 Request Feature

✨ Features

• 🚀 Easy Integration - Simple setup with Express.js applications
• 📚 Interactive Documentation - Beautiful, responsive API documentation interface
• 🔒 Security - Password-protected documentation access
• 🎨 Customizable - Custom headers, colors, icons, and branding
• 📱 Responsive Design - Works perfectly on desktop and mobile devices
• ⚡ Fast Performance - Lightweight and optimized for speed
• 🔧 Framework Agnostic - Works with any Express.js-based application

📖 Table of Contents

• Installation
• Quick Start
• Configuration
• Environment Variables
• API Reference
• Examples
• Contributing
• Support
• License

🚀 Installation

Install node-api-document using npm:

npm install node-api-document

Or using yarn:

yarn add node-api-document

⚡ Quick Start

Get started in minutes with this simple example:

const express = require('express');
const createDoc = require('node-api-document');

const app = express();
const PORT = process.env.PORT || 3000;

// Define your API documentation
const apiDoc = [
  {
    new_tag: "1",
    color: "black",
    title: "COMMON API",
    icon: "list"
  },
  {
    new_tag: "0",
    color: "orange",
    icon: "flag",
    title: "1 : COMMON",
    name: "Get Country List",
    meth: "GET",
    link: "http://localhost:3000/country_list",
    mandatory: "",
    optional: "",
    is_header: "YES",
    is_push: "NO",
    header: "API-KEY",
    notes: "This API is used to get the country list",
    example: "",
    status: "1. HTTP_OK [200] - status : success\n2. HTTP_OK [201] - status : error\n3. HTTP_NOT_FOUND [204]",
    imp: ""
  }
];

// Initialize API documentation
createDoc(app, 'token, api-key', apiDoc);

app.listen(PORT, () => {
  console.log(`🚀 Server running on port ${PORT}`);
  console.log(`📚 API Documentation available at: http://localhost:3000/api-doc/`);
});

⚙️ Configuration

Environment Variables

Create a .env file in your project root and add the following variables:

Required Variables

Variable	Description	Example
APP_NAME	Your project name	APP_NAME=My Awesome API
LOGO_URL	URL for your project logo	LOGO_URL=https://example.com/logo.png
BASE_URL	Base URL for your API	BASE_URL=https://api.example.com
API_PASSWORD	Password to access documentation	API_PASSWORD=your_secure_password

Optional Variables

Variable	Description	Example
LOADER_IMAGE	Custom loader image URL	LOADER_IMAGE=https://example.com/loader.gif
ARROW_IMAGE	Custom arrow image URL	ARROW_IMAGE=https://example.com/arrow.png

Example .env File

# Required Variables
APP_NAME=My Awesome API
LOGO_URL=https://example.com/logo.png
BASE_URL=https://api.example.com
API_PASSWORD=my_secure_password_123

# Optional Variables
LOADER_IMAGE=https://example.com/loader.gif
ARROW_IMAGE=https://example.com/arrow.png

📚 API Reference

createDoc(app, acceptHeaders, apiDoc)

Creates middleware for API documentation and integrates it into your Express app.

Parameters

Parameter	Type	Required	Description
app	Express.Application	✅	The Express.js application instance
acceptHeaders	string	❌	Custom headers to be added to requests
apiDoc	Array	❌	Array of objects defining API documentation structure

Returns

A promise that resolves when the documentation is successfully integrated.

Example

// Basic usage
createDoc(app);

// With custom headers
createDoc(app, 'application/json, authorization');

// With API documentation
createDoc(app, 'token, api-key', apiDoc);

📋 API Documentation Format

Each object in the apiDoc array should follow this structure:

{
  new_tag: "0" | "1",           // Flag to denote new items
  color: "string",              // Display color (e.g., "blue", "orange", "green")
  icon: "string",               // Icon name or URL
  title: "string",              // Title of the documentation section
  name: "string",               // Name of the API or link
  meth: "GET" | "POST" | "PUT" | "DELETE" | "Link", // HTTP method
  link: "string",               // API endpoint or link
  mandatory: "string",          // Mandatory parameters
  optional: "string",           // Optional parameters
  is_header: "YES" | "NO",      // Whether header is required
  is_push: "YES" | "NO",        // Whether push notification is enabled
  header: "string",             // Header name
  notes: "string",              // Additional notes
  example: "string",            // Example request/response
  status: "string",             // Status codes and descriptions
  imp: "string"                 // Important information
}

🎯 Examples

Complete Example with Multiple APIs

const express = require('express');
const createDoc = require('node-api-document');

const app = express();

const apiDoc = [
  // Section Header
  {
    new_tag: "1",
    color: "black",
    title: "AUTHENTICATION API",
    icon: "lock"
  },
  
  // Login API
  {
    new_tag: "0",
    color: "green",
    icon: "login",
    title: "1 : AUTHENTICATION",
    name: "User Login",
    meth: "POST",
    link: "http://localhost:3000/api/auth/login",
    mandatory: "email, password",
    optional: "remember_me",
    is_header: "NO",
    is_push: "NO",
    header: "",
    notes: "Authenticate user and return JWT token",
    example: `{
  "email": "[e-mail]",
  "password": "password123"
}`,
    status: "1. HTTP_OK [200] - Login successful\n2. HTTP_UNAUTHORIZED [401] - Invalid credentials\n3. HTTP_BAD_REQUEST [400] - Missing required fields",
    imp: "Store the returned token for subsequent API calls"
  },
  
  // Section Header
  {
    new_tag: "1",
    color: "black",
    title: "USER MANAGEMENT",
    icon: "users"
  },
  
  // Get User Profile
  {
    new_tag: "0",
    color: "blue",
    icon: "user",
    title: "2 : USER MANAGEMENT",
    name: "Get User Profile",
    meth: "GET",
    link: "http://localhost:3000/api/user/profile",
    mandatory: "",
    optional: "",
    is_header: "YES",
    is_push: "NO",
    header: "Authorization: Bearer <token>",
    notes: "Retrieve current user's profile information",
    example: "",
    status: "1. HTTP_OK [200] - Profile retrieved successfully\n2. HTTP_UNAUTHORIZED [401] - Invalid token\n3. HTTP_NOT_FOUND [404] - User not found",
    imp: "Requires valid JWT token in Authorization header"
  },
  
  // Direct Link Example
  {
    new_tag: "0",
    color: "purple",
    icon: "link",
    title: "EXTERNAL LINKS",
    name: "API Documentation",
    meth: "Link",
    link: "https://node-api-document.vercel.app/",
    imp: "Visit our comprehensive documentation"
  }
];

createDoc(app, 'authorization, content-type', apiDoc);

app.listen(3000, () => {
  console.log('🚀 Server running on port 3000');
  console.log('📚 API Documentation: http://localhost:3000/api-doc/');
});

🔐 Access Documentation

Once your server is running, access the API documentation at:

http://localhost:3000/api-doc/

You'll be prompted to enter the API_PASSWORD you configured in your environment variables.

🛠️ Error Handling

The package includes comprehensive error handling:

createDoc(app, 'token, api-key', apiDoc)
  .then(() => {
    console.log('✅ API documentation initialized successfully');
  })
  .catch((error) => {
    console.error('❌ Error initializing API documentation:', error);
  });

🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

How to Contribute

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/tirth-gaudani/node-api-document.git

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

🆘 Support

• 📖 Documentation - Comprehensive guides and examples
• 🐛 Issues - Report bugs or request features
• 💬 Discussions - Ask questions and share ideas

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

• 🌐 Portfolio
• 💼 LinkedIn

Made with ❤️ for the Node.js community