ServerDocs - API Documentation Generator

A simple package for generating beautiful API documentation from JavaScript objects. Perfect for development and testing environments.

Installation

For Development:

npm i serverdocs --save-dev

Or for Development Dependencies:

npm i -D serverdocs

Quick Start (Development Mode)

import docs from "serverdocs";

// Development setup - only enable in dev environment
if (process.env.NODE_ENV !== "production") {
  app.get("/docs", docs(data));
  app.get("/api-docs", docs(data)); // Alternative route
  console.log("📚 API Documentation available at: http://localhost:3000/docs");
}

Development Tips:

• Use /docs or /api-docs routes for easy access
• Only enable in development environment
• Great for testing API endpoints during development
• Perfect for sharing API specs with your development team

How It Works

Create your API documentation by building objects step by step: Info → Tags → Routes → Parameters

Step 1: Create Your API Info

Start with basic information about your API:

const apiInfo = {
  name: "My Store API",
  version: "1.0.0-dev",
  description: "API for managing an online store - Development Version",
  baseUrl: "http://localhost:3000/api", // Development server
  tags: [], // We'll add tags next
};

Development BaseUrl Examples:

• http://localhost:3000/api - Local Express server
• http://localhost:8000/api - Local development server
• http://127.0.0.1:3000/api - Local IP address
• http://dev-api.myapp.com - Development staging server

All Info Properties:

• name - Your API name (required)
• version - Version number like "1.0.0" (required)
• description - What your API does (required)
• baseUrl - Your API's base URL (required)
• tags - List of tag objects (required, can be empty array)

Step 2: Create Tags (Groups of Endpoints)

Tags group related API endpoints together:

const usersTag = {
  name: "Users",
  description: "Manage user accounts and profiles",
  operations: [], // We'll add routes next
};

const productsTag = {
  name: "Products",
  description: "Manage store products and inventory",
  operations: [], // We'll add routes next
};

All Tag Properties:

• name - Name for this group of endpoints (required)
• description - What this group of endpoints does (required)
• operations - List of route objects (required, can be empty array)

Step 3: Create Routes (Individual Endpoints)

Each route represents one API endpoint:

GET Route Example:

const getUserRoute = {
  path: "/users/123",
  method: "GET",
  description: "Get user details by ID",
  authRequired: true,
  headers: {
    Authorization: "Bearer your-token",
    "Content-Type": "application/json",
  },
  queryParams: {}, // We'll add params next
  body: {},
  responses: {
    200: "Success - User found",
    404: "User not found",
    401: "Not authorized",
  },
  responseExample: {
    id: 123,
    name: "John Smith",
    email: "[email protected]",
  },
};

POST Route Example (with body and schema):

const createUserRoute = {
  path: "/users",
  method: "POST",
  description: "Create a new user account",
  authRequired: true,
  headers: {
    Authorization: "Bearer <token>",
  },
  queryParams: {},
  schema: {
    key: "string (required)",
    role: "string",
  },
  body: {
    name: "Alice Johnson",
    email: "[email protected]",
    password: "password123",
    role: "user",
  },
  responses: {
    201: "User created successfully",
    400: "Invalid input data",
    401: "Not authorized",
  },
  responseExample: {
    id: 124,
    name: "Jane Doe",
    email: "[email protected]",
    created_at: "2024-01-15T10:30:00Z",
  },
};

PUT Route Example (with body and schema):

const updateUserRoute = {
  path: "/users/123",
  method: "PUT",
  description: "Update existing user information",
  authRequired: true,
  headers: {
    Authorization: "Bearer your-token",
    "Content-Type": "application/json",
  },
  queryParams: {},
  schema: {
    name: "string (required)",
    email: "string",
  },
  responses: {
    200: "User updated successfully",
    400: "Invalid input data",
    404: "User not found",
    401: "Not authorized",
  },
  responseExample: {
    id: 123,
    name: "John Smith Updated",
    email: "[email protected]",
    updated_at: "2024-01-15T12:45:00Z",
  },
};

All Route Properties:

• path - The endpoint path like "/users/123" (required)
• method - HTTP method: "GET", "POST", "PUT", "DELETE" (required)
• description - What this endpoint does (required)
• authRequired - true or false if auth needed (optional)
• headers - Object with header names and example values (optional)
• queryParams - Object with query parameter objects (optional)
• body - Object with request body example data (optional)
• schema - Object with request body data types and validation (optional)
• responses - Object with status codes and messages (required)
• responseExample - Example response object (required)

Step 4: Create Parameters (Query & Body Parameters)

Parameters provide extra options for your endpoints:

// Note: Parameters go directly in queryParams object, no separate name property needed
const getUserRoute = {
  path: "/users",
  method: "GET",
  queryParams: {
    sortOrder: {
      description:
        "Specify sort direction: ascending (asc) or descending (desc)",
      example: "?sortOrder=desc",
      possibleValues: ["asc", "desc"],
    },
    dateTo: {
      description: "End date for filtering (ISO 8601 format)",
      example: "?dateTo=2024-01-31T23:59:59Z",
    },
    limit: {
      description: "Maximum number of items to return per page",
      example: "?limit=50",
      possibleValues: ["10", "20", "50", "100"],
    },
  },
};

All Parameter Properties:

• description - What this parameter does (required)
• example - Example usage like "?limit=50" (required)
• possibleValues - List of valid values (optional)

Step 5: Put It All Together

Now connect everything step by step:

// 1. First create your parameters
const sortParam = {
  name: "sort",
  description: "Sort order for results",
  example: "sort=name",
  possibleValues: ["name", "price", "date"],
};

// 2. Then create your routes and add the parameters
const getProductsRoute = {
  path: "/products",
  method: "GET",
  description: "Get list of all products",
  authRequired: false,
  headers: {
    Accept: "application/json",
  },
  queryParams: {
    sort: sortParam, // Add your parameter here
  },
  body: {},
  responses: {
    200: "Success - Products found",
    400: "Bad request",
  },
  responseExample: {
    products: [
      { id: 1, name: "Laptop", price: 999 },
      { id: 2, name: "Phone", price: 599 },
    ],
  },
};

// 3. Then create your tags and add the routes
const productsTag = {
  name: "Products",
  description: "Manage store products",
  operations: [getProductsRoute], // Add your route here
};

// 4. Finally create your API info and add the tags
const apiDocs = {
  name: "My Store API - Dev",
  version: "1.0.0-dev",
  description: "Simple store management API - Development Version",
  baseUrl: "http://localhost:3000/api", // Development URL
  tags: [productsTag], // Add your tag here
};

// 5. Use it in your development server
if (process.env.NODE_ENV !== "production") {
  app.get("/docs", docs(apiDocs));
  app.get("/api-docs", docs(apiDocs));
}

Development Workflow

1. Setup in your development server:

// server.js or app.js
import express from "express";
import docs from "serverdocs";
import { data } from "./api-documentation.js";

const app = express();

// Only enable docs in development
if (process.env.NODE_ENV !== "production") {
  app.get("/docs", docs(data));
  console.log("📚 API Docs: http://localhost:3000/docs");
}

app.listen(3000);

2. Create separate documentation file:

// api-documentation.js
export const apiDocs = {
  name: "My API - Development",
  version: "1.0.0-dev",
  description: "API Documentation for Development Team",
  baseUrl: "http://localhost:3000/api",
  tags: [
    /* your tags */
  ],
};

3. Development Benefits:

• 📖 Live Documentation - Always up-to-date with your code
• 🔄 Quick Testing - Test endpoints directly from docs
• 👥 Team Sharing - Share API specs with developers
• 🐛 Debug Helper - See request/response examples
• 📝 No External Tools - Built into your development server

Features

• 🎨 Modern Design - Clean, professional interface
• 📱 Mobile Friendly - Works on phones and tablets
• 🔍 Easy to Use - Simple JavaScript objects
• 📋 Copy Examples - Click to copy code samples
• ⚡ Fast - Generates docs quickly
• 🎯 Complete - Shows all your API details