{}
APIDocly

Documentation

APIDocly generates beautiful API documentation from JSDoc-style comments in your source code.

Installation

Terminal
$ npm install -g apidocly

Basic Usage

Terminal
$ apidocly -i ./src -o ./docs

CLI Options

-i, --input <path>

Input source files path. Default: ./

-o, --output <path>

Output documentation path. Default: ./docs

-c, --config <path>

Path to configuration file (apidocly.json)

--private

Include endpoints marked with @apiPrivate

--single-file

Generate a single HTML file with all CSS and JS embedded

--verbose

Show detailed output during generation

Configuration File

Create an apidocly.json file in your project root:

apidocly.json
{
  "name": "My API",
  "version": "1.0.0",
  "description": "API Description",
  "title": "My API Documentation",
  "url": "https://api.example.com",
  "sampleUrl": "https://api.example.com",
  "environments": [
    { "name": "Development", "url": "http://localhost:3000" },
    { "name": "Production", "url": "https://api.example.com" }
  ],
  "password": "your-password",
  "template": {
    "withCompare": true,
    "withGenerator": true
  }
}

Configuration Options

OptionTypeDescription
nameStringProject name
versionStringProject version
descriptionStringProject description
titleStringDocumentation page title
urlStringBase API URL
sampleUrlStringURL for sample requests (fallback)
environmentsArrayList of API environments with name and url
passwordStringPassword for protected docs
passwordMessageStringLogin prompt message
header.filenameStringPath to header content file
footer.filenameStringPath to footer content file

Environment Switching

Define multiple API environments to easily switch between different servers when testing endpoints in the "Try it out" section.

When to use environments

Environments are perfect for teams that need to test APIs against different servers - development, staging, and production. The selected environment is saved in the browser, so users don't need to switch every time they visit.

Configuration

Add an environments array to your config file:

apidocly.json
{
  "name": "My API",
  "version": "1.0.0",
  "environments": [
    {
      "name": "Development",
      "url": "http://localhost:3000"
    },
    {
      "name": "Staging",
      "url": "https://staging.api.example.com"
    },
    {
      "name": "Production",
      "url": "https://api.example.com"
    }
  ]
}

Environment Object

PropertyTypeDescription
nameStringDisplay name shown in the dropdown selector
urlStringBase URL for API requests in this environment

How it works

1

Environment selector appears

When environments are defined, a dropdown appears in the header

2

Selection is remembered

The selected environment is stored in localStorage

3

Try it out uses selected URL

All API requests use the URL from the selected environment

Priority order

URL priority: @apiSampleRequest (per endpoint) → Selected environment → sampleUrl (fallback)

Basic Annotations

@api

Defines an API endpoint. Required for each endpoint.

@api {method} path [title]

method: HTTP method (get, post, put, patch, delete)

path: API endpoint path

title: Short description (optional)

@apiName

Unique identifier for the endpoint.

@apiName GetUsers

@apiGroup

Groups endpoints in the sidebar navigation. Default: Default

@apiGroup Users

@apiVersion

API version number. Default: 1.0.0

@apiVersion 2.0.0

@apiDescription

Detailed description of the endpoint.

@apiDescription Returns a list of all users in the system.

@apiPermission

Required permission or role to access the endpoint.

@apiPermission admin

@apiDeprecated

Marks the endpoint as deprecated.

@apiDeprecated Use /v2/users instead

@apiPrivate

Hides the endpoint from documentation (unless --private flag is used).

@apiPrivate

@apiIgnore

Completely excludes the endpoint from documentation.

@apiIgnore Not ready for production

@apiSampleRequest

URL for sample request testing.

@apiSampleRequest https://api.example.com

Parameter Annotations

@apiParam

URL path parameter.

@apiParam [(group)] {type} [field=default] description
Example
@apiParam {String} id User's unique ID
@apiParam {Number} [limit=10] Number of results (optional)
@apiParam (Authentication) {String} token Auth token

@apiQuery

Query string parameter.

@apiQuery {String} [search] Search term
@apiQuery {Number} [page=1] Page number

@apiBody

Request body parameter.

@apiBody {String} email User's email
@apiBody {String} password User's password
@apiBody {Object} profile Profile data
@apiBody {String} profile.name Display name

@apiHeader

Request header.

@apiHeader {String} Authorization Bearer token
@apiHeader {String} [Accept-Language=en] Language preference

Response Annotations

@apiSuccess

Success response field. Default group: Success 200

@apiSuccess {Object} user User object
@apiSuccess {String} user.id User ID
@apiSuccess {String} user.email User email
@apiSuccess (201) {Object} data Created resource

@apiError

Error response field. Default group: Error 4xx

@apiError {404} NotFound User not found
@apiError {401} Unauthorized Invalid token
@apiError {422} ValidationError Invalid input

Example Annotations

@apiExample

Request example.

@apiExample {curl} Example usage:
curl -X GET https://api.example.com/users/123

@apiSuccessExample

Success response example.

@apiSuccessExample {json} Success-Response:
HTTP/1.1 200 OK
{
  "user": {
    "id": "123",
    "email": "user@example.com"
  }
}

@apiErrorExample

Error response example.

@apiErrorExample {json} Error-Response:
HTTP/1.1 404 Not Found
{
  "error": "User not found"
}

@apiParamExample / @apiHeaderExample

Parameter and header examples.

@apiParamExample {json} Request-Example:
{
  "email": "user@example.com",
  "password": "secret123"
}

@apiHeaderExample {json} Header-Example:
{
  "Authorization": "Bearer eyJhbG..."
}

Reusability

@apiDefine

Define reusable documentation blocks.

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

@apiUse

Include a defined block.

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

Type System

Supported type modifiers:

{String}

Basic string type

{Number}

Numeric type

{Boolean}

Boolean type

{Object}

Object type

{String[]}

Array of strings

{String{1..255}}

String with size constraint

{String=a,b,c}

Allowed values (enum)

[field]

Optional parameter

[field=value]

Optional with default

field.nested

Nested object property

OpenAPI Export

APIDocly automatically generates an OpenAPI 3.0 specification file alongside your documentation. This file can be used with AI assistants, code generators, and API testing tools.

AI Integration Tip

Download the openapi.json file and feed it directly to ChatGPT, Claude, or any AI assistant. Ask it to generate API client code, TypeScript interfaces, Zod schemas, or complete integration modules in any programming language. The structured format helps AI understand your entire API instantly.

Generated Files

openapi.json

Complete OpenAPI 3.0 specification with all endpoints, parameters, and schemas.

openapi.yaml

Same specification in YAML format for better readability.

Use Cases

AI Code Generation

Feed to AI assistants for instant client code in any language

Type Generation

Generate TypeScript interfaces, Zod schemas, or Pydantic models

API Testing

Import into Postman, Insomnia, or other API testing tools

SDK Generation

Use with OpenAPI Generator for official SDK creation

Supported Languages

JavaScript/TypeScript

Uses JSDoc block comments

.js .jsx .ts .tsx .mjs .cjs

PHP

Uses PHPDoc block comments

.php

Python

Uses docstrings

.py

Comment Syntax Examples

JavaScript/PHP
/**
 * @api {get} /users
 */
Python
"""
@api {get} /users
"""
Python (alt)
'''
@api {get} /users
'''

Password Protection

APIDocly supports password protection with AES-256-GCM encryption for your API documentation.

Plain Text Password

When you provide a plain text password, the API data is encrypted using AES-256-GCM with PBKDF2 key derivation. 

"password": "my-secret-password"

Pre-hashed Password

Use a SHA-256 hash prefix if you don't want to store plain text password. Note: This disables encryption. 

"password": "sha256:e3b0c44298fc..."