node-api-document/README.md

🚀 Generate beautiful, interactive API documentation for Node.js/Express applications with zero configuration. Features include password protection, custom branding, responsive design, and easy integration. Perfect for REST APIs, microservices, and web ap

# node-api-document
![npm version](https://badge.fury.io/js/node-api-document.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Downloads](https://img.shields.io/npm/dm/node-api-document.svg)

**Generate Beautiful API Documentation for Node.js Applications**
- [🌐 **Live Documentation**](https://node-api-document.vercel.app/) 
- [📦 **NPM Package**](https://www.npmjs.com/package/node-api-document) 
- [🐛 **Report Bug**](https://github.com/tirth-gaudani/node-api-document/issues) 
- [💡 **Request Feature**](https://github.com/tirth-gaudani/node-api-document/issues)

---

## ✨ 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](#-installation)
- [Quick Start](#-quick-start)
- [Configuration](#-configuration)
- [Environment Variables](#-environment-variables)
- [API Reference](#-api-reference)
- [Examples](#-examples)
- [Contributing](#-contributing)
- [Support](#-support)
- [License](#-license)

## 🚀 Installation

Install `node-api-document` using npm:

```bash
npm install node-api-document
```

Or using yarn:

```bash
yarn add node-api-document
```

## ⚡ Quick Start

Get started in minutes with this simple example:

```javascript
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

```env
# 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<Object> | ❌ | Array of objects defining API documentation structure |

#### Returns

A promise that resolves when the documentation is successfully integrated.

#### Example

```javascript
// 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:

```javascript
{
  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

```javascript
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": "user@example.com",
  "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:
```javascript
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

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup

```bash
# 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](https://node-api-document.vercel.app/)** - Comprehensive guides and examples
- 🐛 **[Issues](https://github.com/tirth-gaudani/node-api-document/issues)** - Report bugs or request features
- 💬 **[Discussions](https://github.com/tirth-gaudani/node-api-document/discussions)** - Ask questions and share ideas

## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 👨‍💻 Author
- 🌐 **[Portfolio](https://www.tirth-gaudani.ct.ws/)**
- 💼 **[LinkedIn](https://www.linkedin.com/in/tirthgaudani)**

---

**Made with ❤️ for the Node.js community**