or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli.md comment-tags.md configuration.md core-generation.md index.md output-generation.md parsing.md plugins.md

tile.json

Configuration Management

Configuration file handling and option processing for apidoc. The system supports multiple configuration sources and provides flexible project setup options.

Configuration Reader

class Reader {
  constructor(app: App);
  read(): ConfigurationData;
  search(): ConfigurationData;
  getHeaderFooter(config: ConfigurationData): HeaderFooterData;
  findConfigFileInDir(filename: string, dir: string): Partial<ConfigurationData>;
  findFileInSrc(filename: string): string;
}

The Reader class handles discovery and parsing of configuration files from multiple sources.

Constructor:

app (App): Application context object containing options and logger

Methods:

read(): Reads configuration from specified config file or searches for config files
search(): Searches for configuration files in source directories
getHeaderFooter(): Processes header and footer file references
findConfigFileInDir(): Searches for a specific config file in a directory
findFileInSrc(): Finds a file in source directories

Configuration Data

interface ConfigurationData {
  name?: string;
  version?: string;
  description?: string;
  title?: string;
  url?: string;
  sampleUrl?: string;
  input?: string[];
  output?: string;
  template?: TemplateOptions;
  header?: HeaderFooterConfig;
  footer?: HeaderFooterConfig;
  order?: string[];
}

Properties:

name: Project name for documentation
version: Project version
description: Project description
title: Custom browser title for generated documentation
url: Base URL for the API
sampleUrl: URL for sample requests or false to disable
input: Array of input source directories
output: Output directory for generated documentation
template: Template configuration options
header: Header section configuration
footer: Footer section configuration
order: Custom ordering for API groups and endpoints

Header and Footer Configuration

interface HeaderFooterConfig {
  title: string;
  filename: string;
}

interface HeaderFooterData {
  title: string;
  content: string;
}

HeaderFooterConfig:

title: Display title for the section
filename: Path to markdown file containing content

HeaderFooterData:

title: Section title
content: Processed HTML content from markdown file

Template Options

interface TemplateOptions {
  showRequiredLabels?: boolean;
  withCompare?: boolean;
  withGenerator?: boolean;
  aloneDisplay?: boolean;
}

Properties:

showRequiredLabels: Show "required" labels on parameters
withCompare: Enable version comparison features
withGenerator: Show generator information
aloneDisplay: Display mode for single API endpoints

Default Configuration

const defaultConfig: ConfigurationData = {
  name: 'Acme project',
  version: '0.0.0',
  description: 'REST Api'
};

Configuration File Sources

The configuration system searches for configuration in the following order:

1. Explicit Configuration File

When a config file is specified via the config option:

const { createDoc } = require('apidoc');

const result = createDoc({
  config: './apidoc.json',
  src: ['./src'],
  dest: './docs'
});

2. package.json

Configuration can be specified in the apidoc key of package.json:

{
  "name": "my-api",
  "version": "1.0.0",
  "apidoc": {
    "name": "My API Documentation",
    "version": "1.0.0",
    "description": "REST API for my application",
    "title": "My API Docs",
    "url": "https://api.example.com",
    "sampleUrl": "https://api.example.com",
    "template": {
      "showRequiredLabels": true,
      "withCompare": true
    }
  }
}

3. apidoc.json

Dedicated JSON configuration file:

{
  "name": "My API Documentation",
  "version": "1.0.0",
  "description": "REST API for my application",
  "title": "Custom API Browser Title",
  "url": "https://api.example.com",
  "sampleUrl": "https://api.example.com",
  "input": ["src", "lib"],
  "output": "documentation",
  "header": {
    "title": "Introduction",
    "filename": "header.md"
  },
  "footer": {
    "title": "Best Practices",
    "filename": "footer.md"
  },
  "order": [
    "User",
    "Authentication",
    "Posts"
  ],
  "template": {
    "showRequiredLabels": false,
    "withCompare": true,
    "withGenerator": true,
    "aloneDisplay": false
  }
}

4. apidoc.config.js

JavaScript configuration file for dynamic configuration:

module.exports = {
  name: 'My API Documentation',
  version: process.env.API_VERSION || '1.0.0',
  description: 'REST API for my application',
  title: 'My API Docs',
  url: process.env.API_BASE_URL || 'https://api.example.com',
  sampleUrl: process.env.API_BASE_URL || 'https://api.example.com',
  input: ['src'],
  output: 'docs',
  template: {
    showRequiredLabels: process.env.NODE_ENV === 'development',
    withCompare: true,
    withGenerator: true
  }
};

Usage Examples

Basic Configuration Reading

Note: The Reader class is internal to ApiDoc and not part of the public API. This example is for reference only.

const { Reader } = require('apidoc/lib/reader');

const app = {
  options: {
    config: './apidoc.json',
    src: ['./src']
  },
  log: console,
  markdownParser: null
};

const reader = new Reader(app);
const config = reader.read();

console.log(`Project: ${config.name} v${config.version}`);
console.log(`Description: ${config.description}`);

Configuration Search

const { Reader } = require('apidoc/lib/reader');

const app = {
  options: {
    src: ['./src', './lib']
  },
  log: console,
  markdownParser: null
};

const reader = new Reader(app);
const config = reader.search();

if (config.name === 'Acme project') {
  console.log('No configuration files found, using defaults');
} else {
  console.log(`Found configuration: ${config.name}`);
}

Header and Footer Processing

const { Reader } = require('apidoc/lib/reader');
const MarkdownIt = require('markdown-it');

const app = {
  options: {
    config: './apidoc.json'
  },
  log: console,
  markdownParser: new MarkdownIt()
};

const reader = new Reader(app);
const config = reader.read();

// config.header and config.footer now contain processed HTML content
if (config.header) {
  console.log(`Header title: ${config.header.title}`);
  console.log(`Header content length: ${config.header.content.length}`);
}

Custom Configuration Location

const { Reader } = require('apidoc/lib/reader');

const app = {
  options: {
    config: '/path/to/custom/config.js',
    src: ['./src']
  },
  log: console,
  markdownParser: null
};

const reader = new Reader(app);
const config = reader.read();

Configuration Validation

Required Fields

While most configuration fields are optional, certain combinations are recommended:

name and version for proper project identification
input or proper src option for source file location
output for documentation destination

Path Resolution

All file paths in configuration are resolved relative to:

The configuration file directory (for config-specified paths)
The current working directory (for CLI-specified paths)
The first input directory (for header/footer files)

Error Handling

const { Reader } = require('apidoc/lib/reader');

const app = {
  options: {
    config: './invalid-config.json'
  },
  log: console,
  markdownParser: null
};

try {
  const reader = new Reader(app);
  const config = reader.read();
} catch (error) {
  if (error.code === 'ENOENT') {
    console.error('Configuration file not found');
  } else if (error instanceof SyntaxError) {
    console.error('Invalid JSON in configuration file');
  } else {
    console.error('Configuration error:', error.message);
  }
}

Integration Examples

Environment-Based Configuration

// apidoc.config.js
const env = process.env.NODE_ENV || 'development';

module.exports = {
  name: 'My API',
  version: process.env.npm_package_version,
  description: 'API Documentation',
  url: env === 'production' 
    ? 'https://api.mycompany.com' 
    : 'http://localhost:3000',
  sampleUrl: env === 'production' 
    ? 'https://api.mycompany.com' 
    : 'http://localhost:3000',
  template: {
    withCompare: env === 'development',
    withGenerator: true
  }
};

Monorepo Configuration

// apidoc.config.js for monorepo
const path = require('path');

module.exports = {
  name: 'Microservice API',
  version: require('./package.json').version,
  input: [
    path.join(__dirname, 'src'),
    path.join(__dirname, '../shared/src')
  ],
  output: path.join(__dirname, 'docs'),
  header: {
    title: 'API Overview',
    filename: '../shared/docs/header.md'
  }
};