APIDoc is a modern TypeScript-first API documentation generator that creates beautiful, interactive documentation from source code comments with built-in authentication, OpenAPI 3.0 support, and complete MQTT protocol documentation including publish/subscribe patterns.

Is APIDoc free to use?

Yes, APIDoc is completely free and open source under the MIT license. You can use it for personal and commercial projects without any restrictions.

What programming languages does APIDoc support?

APIDoc supports 15+ programming languages including TypeScript, JavaScript, Python, PHP, Java, C#, Go, Ruby, and many more.

APIDoc v4.0.5 - Modern API Documentation Generator

What's New in v4.0.5?

Custom markdown content for API groups, complete MQTT IoT protocol support with 16 specialized tags, dual authentication system, and multi-language documentation support

🆕 Full TypeScript Migration

Complete codebase migration to TypeScript with full type safety, modern ESLint configuration, and enhanced IntelliSense support.

🔐 Dual Authentication System

Protect your API documentation with local authentication, remote integration (Auth0, Firebase), or hybrid setups with AES-256 encryption.

🔥 External OpenAPI Files

Load complete OpenAPI specs from external JSON/YAML files with automatic $ref resolution. Generate full request/response tables from existing specifications.

⚡ @apiSchema Integration

Automatically generate @apiParam, @apiSuccess, and @apiError from TypeScript interfaces and JSON Schema files. Support for nested objects, arrays, and complex types.

🔄 Native OpenAPI 3.0

Write OpenAPI 3.0 specifications directly in comments using @openapi, @openapi-path, and @openapi-schema parsers.

🌟 Complete MQTT Protocol Support

Full support for MQTT publish/subscribe patterns with 16 specialized tags, distinctive purple-themed UI, and interactive collapsible documentation for IoT and real-time systems.

🔄 Interactive Collapsible Templates

Collapsible sections for both REST APIs and MQTT documentation with comprehensive details, smart grouping, and improved navigation for large API specifications.

🔧 Modern Build Pipeline

Node.js 20+, esbuild, TypeDoc API docs, enhanced ESLint, and container support with Podman/Docker.

Advanced Features

Professional tools for modern REST API and MQTT protocol documentation teams

Custom Icons & Localization

Font Awesome integration with custom logos and multilingual group titles

"settings": {
  "Users": {
    "icon": "fa-user",
    "title": "Usuarios"
  }
}

Complete Authentication

Local users, remote API integration, or hybrid setup with session persistence

Local Authentication (SHA256)

Remote API Integration

Hybrid Mode (Local + Remote)

24h Session Persistence

Custom Markdown Content

Add rich markdown content to any API group with custom icons, titles, and external files

Custom icons (Font Awesome)

External markdown files

Rich formatting support

Group-specific titles

"settings": {
  "Users": {
    "icon": "fa-user",
    "title": "User Management",
    "filename": "user.md"
  }
}

TypeScript-First

Complete migration with full type safety, ESLint 9, and TypeDoc API documentation

interface UserProfile {
  id: number;
  email: string;
  role: 'admin' | 'user';
}

Complete OpenAPI 3.0

Native syntax support, external file loading, $ref resolution, and bidirectional conversion

@openapi native syntax

External JSON/YAML files

Automatic $ref resolution

Export to swagger.json

Complete MQTT IoT Support

16 specialized MQTT tags for complete IoT documentation with publish/subscribe patterns

@mqtt publish/subscribe

@topic wildcards

@qos levels

@retain messages

@payload schemas

@auth methods

@ratelimit controls

@tags organization

/**
* @mqtt {publish} v1/sensors/{id}/data
* @mqttGroup IoT
* @topic v1/sensors/{id}/data
* @qos 1
* @retain false
*/

🚀

Ready for Production

Enterprise-ready with all authentication issues fixed in v4.0

Get Started Now

See It In Action

From source code comments to beautiful documentation in minutes

Modern TypeScript + @apiSchema

user.controller.ts

// TypeScript interface
export interface UserProfile {
  id: number;
  email: string;
  name: string;
  role: 'admin' | 'user';
  preferences?: {
    theme: 'light' | 'dark';
    notifications: boolean;
  };
}

/**
 * @api {get} /api/users/:id Get User Profile
 * @apiName GetUserProfile
 * @apiGroup Users
 * @apiVersion 4.0.0
 *
 * @apiParam {Number} id User's unique ID
 *
 * @apiSchema {interface=UserProfile} apiSuccess
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "id": 1,
 *       "email": "john@example.com",
 *       "name": "John Doe",
 *       "role": "user",
 *       "preferences": {
 *         "theme": "dark",
 *         "notifications": true
 *       }
 *     }
 */

Get Beautiful Documentation

apidoc.app

GET /user/:id

Request User Information

Parameters

id Number

User's unique ID

Native OpenAPI 3.0 Support

payment.service.js

/**
 * @openapi
 * /api/payments:
 *   post:
 *     tags:
 *       - Payments
 *     summary: Process payment transaction
 *     description: Creates a new payment with comprehensive validation
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: './schemas/payment.yaml#/components/schemas/PaymentRequest'
 *     responses:
 *       201:
 *         description: Payment processed successfully
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 transactionId:
 *                   type: string
 *                   example: "txn_1234567890"
 *                 status:
 *                   type: string
 *                   enum: [pending, completed, failed]
 *                 amount:
 *                   type: number
 *                   format: decimal
 *                   example: 99.99
 *       400:
 *         description: Invalid payment data
 *       401:
 *         description: Authentication required
 */

External Schema References

payment.yaml

External OpenAPI schema files with $ref resolution

Auto Documentation

Automatic parameter extraction and response documentation

Security Schemas

Bearer tokens, API keys, OAuth2 flows

External File Integration

apidoc.json

{
  "name": "My API Documentation",
  "version": "4.0.0",
  "description": "Comprehensive API with external schemas",
  "title": "Advanced API Docs",
  "url": "https://api.mycompany.com",
  "sampleUrl": "https://api.mycompany.com",

  "openapi": {
    "externalFiles": [
      "./schemas/user.yaml",
      "./schemas/payment.yaml",
      "./schemas/product.yaml"
    ],
    "components": {
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer"
        },
        "apiKey": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      }
    }
  },

  "login": {
    "active": true,
    "urlAuth": "https://auth.mycompany.com/login"
  }
}

Advanced Configuration

External Schema Files

Load OpenAPI schemas from separate YAML/JSON files

• user.yaml - User management schemas
• payment.yaml - Payment processing
• product.yaml - Product catalog

Authentication System

Built-in protection with remote API integration

$ref Resolution

Automatic resolution of external references and dependencies

Get Beautiful Documentation

apidoc.app

GET /user/:id

Request User Information

Parameters

id Number

User's unique ID

View Live Example Read Documentation

Advanced Features v4.0

Powerful new capabilities including MQTT protocol support that make APIDoc the most advanced documentation generator

Built-in Authentication System

Protect your API documentation with a comprehensive authentication system that supports local users, remote authentication (Auth0, Firebase, custom APIs), and hybrid configurations with AES-256 encryption.

Local authentication with predefined users

Remote integration (Auth0, Firebase, custom APIs)

AES-256 encryption for sensitive content

Responsive login forms with dark mode

apidoc.json

{
  "name": "Protected API Documentation",
  "version": "1.0.0",
  "login": {
    "active": true,
    "admited": [
      {
        "email": "admin@company.com",
        "password": "secure_password_2024"
      }
    ],
    "urlAuth": "https://api.company.com/auth/login",
    "value_form": {
      "email": "email",
      "password": "password"
    },
    "response_success": 200,
    "response_error": 401
  }
}

OpenAPI 3.0 Generation

Automatically generate OpenAPI 3.0 (Swagger) specifications from your existing APIDoc comments. Compatible with Postman, Insomnia, API gateways, and modern development workflows.

apidoc -i src/ -o docs/ --openapi

Generates both HTML docs + swagger.json

Output: docs/index.html swagger.json

Generated swagger.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "Get User Profile",
        "tags": ["Users"],
        "parameters": [{
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {"type": "integer"}
        }],
        "responses": {
          "200": {
            "description": "User profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    }
  }
}

@apiSchema Integration

Generate API documentation directly from TypeScript interfaces and JSON Schema files. Eliminate manual @apiParam declarations and keep your docs in sync with your code.

TypeScript Interfaces

Reference interfaces directly with {interface=UserProfile}

JSON Schema Files

Load external schemas with {jsonschema=./path/file.json}

Auto-Sync

Documentation updates automatically when interfaces change

Before vs After

❌ BEFORE (Manual)

/**
 * @apiParam {String} email User email
 * @apiParam {String} name User name
 * @apiParam {String="user","admin"} role
 * @apiParam {Object} [preferences]
 * @apiParam {String} [preferences.theme]
 * @apiParam {Boolean} [preferences.notifications]
 */

✅ AFTER (@apiSchema)

/**
 * @apiSchema {interface=UserProfile} apiParam
 */

Complete Documentation

Everything you need to know about using APIDoc - from basic setup to advanced features

Quick Start

Get up and running in minutes with our simple installation guide.

• Install globally with npm
• Add comments to your code
• Generate beautiful docs
• Deploy anywhere

Multi-Language

Support for 15+ programming languages with their native comment styles.

JavaScript Python PHP Java Ruby Go

Advanced Features

Powerful features for complex documentation needs.

• Version comparison
• Inheritance & reusable blocks
• Custom templates
• Private API filtering

Complete Usage Guide

1 Installation & Setup

Global Installation

Terminal

$ npm install -g @hrefcl/apidoc

Quick Generation

$ apidoc -i src/ -o doc/

Generate docs from 'src' folder to 'doc' folder

Project Installation

Terminal

$ npm install --save-dev @hrefcl/apidoc

Package.json Script

"scripts": {
  "docs": "apidoc -i src/ -o docs/"
}

Advanced Configuration (apidoc.json)

{
  "name": "My Advanced API",
  "version": "4.0.0",
  "description": "Comprehensive API with authentication and external schemas",
  "title": "My Advanced API Documentation",
  "url": "https://api.example.com",
  "sampleUrl": "https://api.example.com",

  "openapi": {
    "externalFiles": [
      "./schemas/user.yaml",
      "./schemas/payment.yaml",
      "./schemas/product.yaml"
    ],
    "components": {
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer"
        },
        "apiKey": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      }
    }
  },

  "login": {
    "active": true,
    "admited": [
      {
        "email": "admin@company.com",
        "password": "secure_password_123"
      }
    ],
    "urlAuth": "https://auth.company.com/login",
    "value_form": {
      "email": "email",
      "password": "password"
    },
    "response_success": 200,
    "response_error": 401
  },

  "header": {
    "title": "Introduction",
    "filename": "header.md"
  },
  "footer": {
    "title": "Footer",
    "filename": "footer.md"
  },
  "order": [
    "User",
    "Authentication",
    "Payments",
    "Products"
  ]
}

Authentication

Protect your docs with local users or remote API authentication

External Schemas

Load OpenAPI schemas from separate YAML/JSON files

Custom Order

Control the order of API groups and sections

2 Comment Syntax by Language

JavaScript/TypeScript

/**
 * @api {get} /user/:id Get User
 * @apiName GetUser
 * @apiGroup User
 */

Python

"""
@api {get} /user/:id Get User
@apiName GetUser
@apiGroup User
"""

Ruby

=begin
@api {get} /user/:id Get User
@apiName GetUser
@apiGroup User
=end

3 Basic API Documentation Example

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 * @apiVersion 1.0.0
 *
 * @apiParam {Number} id User's unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 * @apiSuccess {String} email     Email of the User.
 * @apiSuccess {Number} age       Age of the User.
 * @apiSuccess {Date}   registered Registration Date.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe",
 *       "email": "john@example.com",
 *       "age": 29,
 *       "registered": "2023-01-15T10:30:00Z"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 * @apiError InvalidId The provided ID is not valid.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound",
 *       "message": "User with ID 999 not found"
 *     }
 */

4 APIDoc Parameters Reference

Essential Parameters

@api {method} path title

Required. Defines the API endpoint.

@api {get} /users Get all users

@apiName

Unique name for the API method.

@apiName GetUsers

@apiGroup

Groups related API methods together.

@apiGroup User

@apiVersion

API version for comparison.

@apiVersion 1.2.0

Request Parameters

@apiParam

URL/Form parameters.

@apiParam {Number} id User ID

@apiQuery

Query string parameters.

@apiQuery {String} sort Sort field

@apiBody

Request body parameters.

@apiBody {String} name User name

@apiHeader

Required headers.

@apiHeader {String} Authorization Bearer token

5 Advanced Features

Inheritance & Reusable Blocks

/**
 * @apiDefine UserNotFoundError
 * @apiError UserNotFound User not found.
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     { "error": "UserNotFound" }
 */

/**
 * @api {get} /user/:id Get User
 * @apiUse UserNotFoundError
 */

/**
 * @api {put} /user/:id Update User
 * @apiUse UserNotFoundError
 */

API Versioning

// _apidoc.js - Historical versions
/**
 * @api {get} /user/:id Get User
 * @apiVersion 1.0.0
 * @apiSuccess {String} name Full name
 */

// current file - Latest version
/**
 * @api {get} /user/:id Get User
 * @apiVersion 2.0.0
 * @apiSuccess {String} firstName First name
 * @apiSuccess {String} lastName Last name
 */

6 Command Line Options

Parameter	Description	Example
-i, --input	Input directory	apidoc -i src/
-o, --output	Output directory	apidoc -o doc/
-f, --file-filters	File filter regex	apidoc -f ".*\\.js$"
-e, --exclude-filters	Exclude directories	apidoc -e node_modules
-t, --template	Custom template	apidoc -t mytemplate/

Ready to Start Documenting?

Join thousands of developers who use APIDoc to create beautiful, interactive API documentation.

Get Started Now View Live Demo

Ready to Get Started?

Install APIDoc in seconds and start generating beautiful documentation

terminal

# Install globally

$ npm install -g @hrefcl/apidoc

# Export to OpenAPI 3.0 (NEW in v4.0)

$ apidoc --openapi -i src/ -o doc/ NEW

# Generate TypeScript-ready documentation with auth

$ apidoc -i src/ -o doc/ --typescript --auth

@apiSchema

Dual Auth

Native

MQTT

What's New in v4.0.5?

🆕 Full TypeScript Migration

🔐 Dual Authentication System

🔥 External OpenAPI Files

⚡ @apiSchema Integration

🔄 Native OpenAPI 3.0

🌟 Complete MQTT Protocol Support

🔄 Interactive Collapsible Templates

🔧 Modern Build Pipeline

Advanced Features

Custom Icons & Localization

Complete Authentication

Custom Markdown Content

TypeScript-First

Complete OpenAPI 3.0

Complete MQTT IoT Support

Ready for Production

See It In Action

Modern TypeScript + @apiSchema

Get Beautiful Documentation

Request User Information

Parameters

Native OpenAPI 3.0 Support

External Schema References

External File Integration

Advanced Configuration

External Schema Files

Authentication System

$ref Resolution

Get Beautiful Documentation

Request User Information

Parameters

Advanced Features v4.0

Built-in Authentication System

OpenAPI 3.0 Generation

@apiSchema Integration

Complete Documentation

Quick Start

Multi-Language

Advanced Features

Complete Usage Guide

1 Installation & Setup

Global Installation

Quick Generation

Project Installation

Package.json Script

Advanced Configuration (apidoc.json)

Authentication

External Schemas

Custom Order

2 Comment Syntax by Language

JavaScript/TypeScript

Python

Ruby

3 Basic API Documentation Example

4 APIDoc Parameters Reference

Essential Parameters

@api {method} path title

@apiName

@apiGroup

@apiVersion

Request Parameters

@apiParam

@apiQuery

@apiBody

@apiHeader

5 Advanced Features

Inheritance & Reusable Blocks

API Versioning

6 Command Line Options

Ready to Start Documenting?

Ready to Get Started?

GitHub Repository

NPM Package

Documentation