Complete guide for configuring APIDoc through the apidoc.json
file with all available options and advanced settings.
{
"name": "My API",
"version": "1.0.0",
"description": "API documentation for my application"
}
{
"name": "Company API",
"version": "2.1.0",
"description": "Complete REST API and MQTT documentation",
"title": "Company API Documentation",
"url": "https://api.company.com",
"sampleUrl": "https://api.company.com",
"defaultVersion": "1.0.0",
"apidoc": "0.3.0",
"generator": {
"name": "@hrefcl/apidoc",
"time": "2024-01-15T10:30:00.000Z",
"url": "https://apidoc.app",
"version": "4.0.5"
}
}
Property | Type | Description | Required |
---|---|---|---|
name |
String | Project name | β |
version |
String | Current version | β |
description |
String | Project description | β |
title |
String | Documentation title | β |
url |
String | Base API URL | β |
Property | Type | Description | Default |
---|---|---|---|
sampleUrl |
String | URL for sample requests | false |
defaultVersion |
String | Default API version | "0.0.0" |
apidoc |
String | APIDoc version compatibility | "0.3.0" |
order |
Array | Custom group ordering | [] |
{
"header": {
"title": "Custom API Documentation",
"filename": "./header.md"
},
"footer": {
"title": "Footer Information",
"filename": "./footer.md"
}
}
{
"template": {
"withCompare": true,
"withGenerator": false,
"jQueryAjaxSetup": {
"headers": {
"Authorization": "Bearer token"
}
}
}
}
{
"order": [
"Authentication",
"Users",
"Products",
"Orders",
"Payments",
"Admin"
]
}
{
"sampleUrl": "https://api.example.com",
"template": {
"jQueryAjaxSetup": {
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_TOKEN_HERE"
},
"timeout": 10000
}
}
}
{
"settings": {
"Users": {
"title": "User Management",
"icon": "fa-users",
"filename": "./docs/users-intro.md"
},
"Products": {
"title": "Product Catalog",
"icon": "fa-shopping-cart",
"filename": "./docs/products-intro.md"
}
}
}
project/
βββ apidoc.json
βββ src/
β βββ api/
βββ docs/
β βββ users-intro.md
β βββ products-intro.md
β βββ header.md
βββ output/
{
"login": {
"active": true,
"admited": [
{
"email": "admin@company.com",
"password": "secure123"
},
{
"email": "developer@company.com",
"password": "dev456"
}
]
}
}
{
"login": {
"active": true,
"urlAuth": "https://api.company.com/auth/login",
"method": "POST",
"fields": {
"username": "email",
"password": "password"
}
}
}
{
"login": {
"active": true,
"admited": [
{"email": "admin@company.com", "password": "secure123"}
],
"urlAuth": "https://api.company.com/auth/login"
}
}
{
"mqtt": {
"enabled": true,
"brokerUrl": "mqtt://broker.company.com:1883",
"defaultQos": 1,
"showRetain": true
}
}
{
"openapi": {
"enabled": true,
"version": "3.0.0",
"output": "./openapi.json",
"servers": [
{
"url": "https://api.company.com/v1",
"description": "Production server"
},
{
"url": "https://staging-api.company.com/v1",
"description": "Staging server"
}
]
}
}
{
"typescript": {
"enabled": true,
"schemaValidation": true,
"generateExamples": true,
"includeOptional": true
}
}
{
"template": {
"withCompare": true,
"withGenerator": false,
"aloneDisplay": false,
"showRequiredLabels": true,
"markdown": {
"gfm": true,
"tables": true,
"breaks": false,
"pedantic": false,
"sanitize": false,
"smartLists": true,
"smartypants": false
}
}
}
{
"template": {
"jQueryAjaxSetup": {
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer token",
"X-API-Key": "your-api-key"
},
"timeout": 15000,
"cache": false
}
}
}
{
"language": "en",
"languages": {
"en": "English",
"es": "EspaΓ±ol",
"fr": "FranΓ§ais"
}
}
{
"generator": {
"name": "@hrefcl/apidoc",
"time": "2024-01-15T10:30:00.000Z",
"url": "https://apidoc.app",
"version": "4.0.5"
}
}
{
"debug": true,
"verbose": true,
"silent": false,
"log": {
"level": "info",
"file": "./apidoc.log"
}
}
{
"name": "Company API",
"version": "2.1.0",
"description": "Complete API documentation with MQTT support",
"title": "Company API Documentation",
"url": "https://api.company.com",
"sampleUrl": "https://api.company.com",
"defaultVersion": "1.0.0",
"order": [
"Authentication",
"Users",
"Products",
"Orders",
"MQTT"
],
"settings": {
"Users": {
"title": "User Management",
"icon": "fa-users",
"filename": "./docs/users.md"
},
"Products": {
"title": "Product Catalog",
"icon": "fa-shopping-cart",
"filename": "./docs/products.md"
}
},
"login": {
"active": true,
"admited": [
{"email": "admin@company.com", "password": "secure123"}
],
"urlAuth": "https://api.company.com/auth/login"
},
"mqtt": {
"enabled": true,
"defaultQos": 1
},
"openapi": {
"enabled": true,
"output": "./openapi.json"
},
"typescript": {
"enabled": true,
"schemaValidation": true
},
"template": {
"withCompare": true,
"jQueryAjaxSetup": {
"headers": {
"Authorization": "Bearer token"
}
}
}
}
This configuration enables all major APIDoc 4.0 features including custom markdown, MQTT support, authentication, OpenAPI export, and TypeScript integration.