📘 Apibooks v2.2 - Professional API Documentation

Apibooks is a powerful, feature-rich API documentation generator for Express.js that makes creating beautiful, interactive API documentation effortless.

Current Version: 2.2.0 - Complete Feature Overhaul! 🎉

✨ What's New in v2.2

🔒 Security & Performance

• ✅ Fixed critical eval() vulnerability
• ⚡ HTML caching system with configurable TTL
• 🛡️ Input validation for all configuration options
• 🚀 40-60% faster page loads with cache enabled

📤 Export Features

• 📝 Markdown Export - Full documentation in .md format
• 📮 Postman Collection - Import directly into Postman
• 🔄 OpenAPI 3.0 JSON - Standard API specification

🎯 User Experience

• ⭐ Favorites System - Star your most-used endpoints
• 🔗 Anchor Links - Share direct links to specific endpoints
• ⌨️ Keyboard Shortcuts - Navigate documentation like a pro
• 🔍 Enhanced Search - Real-time filtering with keyboard support
• 🏷️ Tags & Categories - Organize endpoints by functionality

💻 Developer Experience

• 📘 Full TypeScript Support - Complete type definitions
• 🎮 API Playground - Test endpoints directly from docs
• 🎨 6 Professional Themes - Plus custom theme support
• 🔄 Hot Reload - Auto-refresh on file changes

🚀 Quick Start

Installation

npm install apibooks

Basic Usage

const express = require("express");
const apiDoc = require("apibooks");

const app = express();
app.use(express.json());

// Define your routes
app.get("/hello", (req, res) => {
  res.json({ message: "Hello, World!" });
});

app.post("/user", (req, res) => {
  const { name, email } = req.body;
  res.status(201).json({ message: "User created", name, email });
});

// Initialize documentation
const doc = apiDoc(app, {
  name: "My Awesome API",
  endpoint: "/docs",
  theme: "ocean",
  baseUrl: "https://api.myapp.com"
});

// Add documentation
doc.requireDocs("/hello", "GET", {
  description: "Returns a welcome message",
  responses: {
    "200": { message: "Hello, World!" }
  }
});

doc.requireDocs("/user", "POST", {
  description: "Create a new user",
  tags: ["Users", "Authentication"],  // NEW in v2.2!
  parameters: [
    { name: "name", type: "string", in: "body", required: true },
    { name: "email", type: "string", in: "body", required: true }
  ],
  responses: {
    "201": { message: "User created" },
    "400": "Bad request - missing fields"
  }
});

app.listen(3000, () => {
  console.log("Server: http://localhost:3000");
  console.log("Docs: http://localhost:3000/docs");
});

TypeScript Usage

import express, { Application } from 'express';
import apiDoc, { ApiBooksOptions, ExpressApiDoc } from 'apibooks';

const app: Application = express();

const options: ApiBooksOptions = {
  name: "My Typed API",
  theme: "purple",
  cache: true,
  cacheTTL: 120000,
  playground: true
};

const doc: ExpressApiDoc = apiDoc(app, options);

doc.requireDocs("/users", "GET", {
  description: "Retrieve all users",
  tags: ["Users"],
  parameters: [
    { name: "page", type: "number", in: "query", required: false }
  ]
});

📋 Complete Configuration

const doc = apiDoc(app, {
  // Basic Configuration
  name: "My API",                    // Documentation title
  endpoint: "/docs",                 // Documentation URL path
  baseUrl: "https://api.example.com", // Base URL for code samples

  // Appearance
  theme: "ocean",                    // Theme: default, ocean, forest, sunset, purple, rose
  logo: "https://example.com/logo.png", // Logo URL
  logoSize: 48,                      // Logo size in pixels
  showIntroduction: true,            // Show auto-generated introduction

  // Performance
  cache: true,                       // Enable HTML caching
  cacheTTL: 60000,                   // Cache duration (ms)

  // Features
  playground: true,                  // Enable API testing playground
  categories: {                      // Organize endpoints by category
    "Users": ["User Management", "Authentication"],
    "Products": ["Inventory", "Orders"]
  },

  // Versioning
  version: "2.2.0",                  // Current API version
  versions: {                        // Multi-version support (future)
    "2.2.0": { baseUrl: "https://api.example.com/v2" },
    "1.0.0": { baseUrl: "https://api.example.com/v1" }
  },

  // Hot Reload
  requireDocs: {
    hotReload: true,                 // Auto-reload on file changes
    openapi: false                   // Load from OpenAPI file
  },
  fileWatch: ['./server.js'],        // Files to watch

  // OpenAPI
  openapi: "./openapi.json"          // OpenAPI file path
});

🎨 Themes

Apibooks includes 6 beautiful built-in themes:

// Built-in themes
theme: "default"  // 🔵 Indigo primary with neutral grays
theme: "ocean"    // 🌊 Sky blue with oceanic tones
theme: "forest"   // 🌲 Emerald green with nature colors
theme: "sunset"   // 🌅 Warm amber and golden hues
theme: "purple"   // 💜 Vibrant purple with elegant accents
theme: "rose"     // 🌹 Pink/rose with soft romantic colors

// Custom theme
theme: {
  primary: '#FF6B6B',
  backgroundLight: '#F8F9FA',
  backgroundDark: '#0D1117',
  surfaceLight: '#FFFFFF',
  surfaceDark: '#161B22',
  textLight: '#1A1A1A',
  textDark: '#E6EDF3',
  subtleLight: '#6B7280',
  subtleDark: '#9CA3AF',
  borderLight: '#E5E7EB',
  borderDark: '#30363D',
  codeBgDark: '#0D1117'
}

📤 Export Features

Available Exports

1. OpenAPI JSON: GET /docs/openapi.json
2. Markdown: GET /docs/export/markdown
3. Postman Collection: GET /docs/export/postman

Export from UI

Click the Export button in the documentation header to access the dropdown menu with all export options.

Programmatic Export

// Generate Markdown
const markdown = doc.generateMarkdown();
fs.writeFileSync('API.md', markdown);

// Generate Postman Collection
const postman = doc.generatePostmanCollection();
fs.writeFileSync('collection.json', JSON.stringify(postman, null, 2));

// Generate OpenAPI Spec
const openapi = doc.generateOpenApiSpec();
fs.writeFileSync('openapi.json', JSON.stringify(openapi, null, 2));

🏷️ Tags & Categories

Organize your endpoints with tags for better structure:

doc.requireDocs("/users", "GET", {
  description: "Get all users",
  tags: ["Users", "Public"],  // Multiple tags supported
  parameters: [/* ... */]
});

doc.requireDocs("/users/:id", "DELETE", {
  description: "Delete a user",
  tags: ["Users", "Admin"],  // Different tags for admin endpoints
  parameters: [/* ... */]
});

Tags are used to:

• Group endpoints in Postman collections
• Organize documentation sections
• Filter and search endpoints

⭐ Favorites System

User Features

• Click the ⭐ icon on any endpoint to add it to favorites
• Click the favorites button (header) to toggle favorites-only view
• Favorites are stored in browser localStorage
• Keyboard shortcut: Alt + F

Perfect For

• Frequently accessed endpoints
• Endpoints you're currently working on
• Important admin or debugging routes

⌨️ Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Alt + D | Toggle dark mode | | Alt + F | Toggle favorites view | | Alt + S | Focus search input | | Ctrl/Cmd + K | Quick search (select all) | | Escape | Clear search (when focused) | | Alt + ? | Show keyboard shortcuts help |

Navigation

• Click any endpoint in sidebar for smooth scroll
• Use anchor links (🔗 icon) to share direct links
• URL hashes are preserved (e.g., /docs#getusers)

🎮 API Playground

Test your endpoints directly from the documentation:

// Enable playground (enabled by default)
const doc = apiDoc(app, {
  playground: true
});

Test Endpoint

POST /docs/playground/test

{
  "method": "GET",
  "path": "/users",
  "headers": {
    "Authorization": "Bearer token"
  },
  "body": {}
}

Note: Full interactive playground UI coming in v2.2!

🔄 Hot Reload

Automatically reload documentation when files change:

const doc = apiDoc(app, {
  requireDocs: {
    hotReload: true
  },
  fileWatch: [
    './server.js',
    './routes/api.js',
    './routes/users.js'
  ]
});

What's Reloaded:

• ✅ requireDocs() definitions
• ✅ Route structure
• ✅ Theme configuration
• ✅ OpenAPI file changes

Not Reloaded (requires restart):

• ❌ Route handlers logic
• ❌ Middleware changes

🚀 Advanced Features

Auto-Detection

Apibooks automatically detects:

app.post("/users/:id", (req, res) => {
  const { id } = req.params;        // ✅ Detected: path parameter
  const { page, limit } = req.query; // ✅ Detected: query parameters
  const { name, email } = req.body;  // ✅ Detected: body parameters

  if (!name) {
    return res.status(400).json({ error: "Name required" });
  }

  res.status(201).json({ id, name, email });
});
// ✅ Auto-detected status codes: 400, 201

WebSocket Documentation

doc.requireDocs("/chat", "WS", {
  description: "Real-time chat WebSocket",
  parameters: [
    { name: "message", type: "string", in: "body" }
  ],
  responses: {
    "101": "Switching Protocols - WebSocket established"
  }
});

Multi-Language Code Samples

Auto-generated for every endpoint:

• Node.js (axios)
• Python (requests)
• PHP (cURL)
• cURL command-line

🛠️ API Reference

Main Methods

requireDocs(endpoint, [method], spec)

Add documentation for an endpoint.

// Method-specific
doc.requireDocs("/users", "GET", {
  description: "Get all users",
  tags: ["Users"],
  parameters: [],
  responses: {}
});

// All methods
doc.requireDocs("/users", {
  description: "User endpoint",
  // ...
});

generateHTML()

Generate the HTML documentation (with caching).

const html = doc.generateHTML();

generateMarkdown()

Generate Markdown documentation.

const md = doc.generateMarkdown();

generatePostmanCollection()

Generate Postman collection.

const collection = doc.generatePostmanCollection();

generateOpenApiSpec()

Generate OpenAPI 3.0 specification.

const spec = doc.generateOpenApiSpec();

loadFromOpenApi(path)

Load documentation from OpenAPI file.

await doc.loadFromOpenApi('./openapi.json');

📊 Performance Tips

Enable Caching

const doc = apiDoc(app, {
  cache: true,        // Enable cache
  cacheTTL: 120000    // 2 minutes
});

Results:

• First request: ~200ms
• Cached requests: ~5-10ms (40-60x faster!)

Invalidate Cache Manually

doc._invalidateCache();

Cache is auto-invalidated when:

• requireDocs() is called
• Files change (with hot reload)

🌐 Browser Support

• ✅ Chrome/Edge (latest)
• ✅ Firefox (latest)
• ✅ Safari (latest)
• ✅ Mobile browsers (iOS Safari, Chrome Mobile)

📱 Responsive Design

Apibooks is fully responsive:

• Desktop: Full sidebar, table layouts
• Tablet: Collapsible sidebar, optimized spacing
• Mobile: Hidden sidebar (hamburger menu), card-based parameters

🔐 Security

Fixed in v2.2

• ❌ Removed eval() usage (critical vulnerability)
• ✅ Safe JSON parsing
• ✅ Input validation
• ✅ Enhanced HTML escaping

Best Practices

• Never expose documentation in production (use environment checks)
• Use authentication middleware if exposing docs
• Validate all user inputs

// Example: Protect documentation in production
if (process.env.NODE_ENV !== 'production') {
  const doc = apiDoc(app, { /* ... */ });
}

🤝 Contributing

We welcome contributions!

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

Areas to contribute:

• New themes
• Language translations
• More code sample languages
• Interactive playground UI
• Bug fixes

📜 License

MIT License - free for personal and commercial use!

🙏 Support the Project

⭐ Star the repo - https://github.com/Aiglator/apibooks 📢 Share with your network 🐛 Report bugs - https://github.com/Aiglator/apibooks/issues 💻 Contribute to the codebase

📞 Resources

• NPM: https://www.npmjs.com/package/apibooks
• GitHub: https://github.com/Aiglator/apibooks
• Issues: https://github.com/Aiglator/apibooks/issues
• Changelog: CHANGELOG.md

🏆 Why Choose Apibooks?

✅ Zero Configuration - Works out of the box ✅ TypeScript Ready - Full type definitions included ✅ Beautiful UI - 6 themes + dark mode + responsive ✅ Smart Auto-Detection - Minimal manual documentation ✅ Export Anywhere - Markdown, Postman, OpenAPI ✅ Developer Friendly - Keyboard shortcuts, favorites, search ✅ High Performance - HTML caching, lazy loading ✅ Open Source - Free forever, community-driven ✅ Active Development - Regular updates and improvements

Made with ❤️ by Rayan Chattaoui

Apibooks v2.2 - Making API documentation beautiful and effortless

Happy documenting! ✨