Development

Guide for contributing to the api-docs CLI.

Prerequisites

• Node.js 20.0.0 or higher
• npm
• Git

Setup

1. Clone the repository:

   git clone https://github.com/TidalStudio/api-docs-cli.git
   cd api-docs-cli

2. Install dependencies:

   npm install

3. Run the CLI locally:

   node bin/api-docs.js --help

Project Structure

api-docs-cli/
  bin/
    api-docs.js         # CLI entry point (yargs commands)
  src/
    browser.js          # Puppeteer browser lifecycle
    cache.js            # Local spec caching with TTL
    discovery.js        # APITracker.io provider lookup
    formatter.js        # Terminal output formatting
    extractors/
      apitracker.js     # APITracker.io search
      docs-scraper.js   # DOM scraping (Scalar, Redoc, generic)
      openapi.js        # Direct OpenAPI/Swagger fetch
      redoc.js          # Redoc-specific extraction
      swagger-ui.js     # Swagger UI extraction via Puppeteer
  wiki/                 # Wiki documentation
  package.json
  eslint.config.js
  .prettierrc

Key Modules

bin/api-docs.js

Main CLI entry point using yargs. Defines all commands and orchestrates extraction.

src/cache.js

Handles local caching of API specs with SHA256-based keys and TTL expiration.

src/discovery.js

Looks up provider names via APITracker.io with 7-day cache.

src/extractors/

Multiple extraction strategies that are tried in order:

1. openapi.js - Direct fetch for .json/.yaml URLs
2. docs-scraper.js - DOM scraping for Scalar/Redoc/generic pages
3. swagger-ui.js - Puppeteer extraction for JS-rendered Swagger UI

src/formatter.js

Formats endpoints for terminal output with color-coded HTTP methods.

src/browser.js

Singleton pattern for Puppeteer browser management.

Scripts

Script	Description
npm start	Run CLI
npm run lint	Run ESLint
npm run lint:fix	Fix ESLint issues
npm run format	Format with Prettier
npm run format:check	Check formatting
npm test	Run tests
npm run test:smoke	Basic smoke test
npm run release	Publish new version

Code Style

• ESLint for linting
• Prettier for formatting
• ES Modules ("type": "module")

Run before committing:

npm run lint:fix
npm run format

Testing

# Run all tests
npm test

# Smoke test (CLI loads correctly)
npm run test:smoke

Making Changes

1. Create a feature branch:

   git checkout -b feature/your-feature

2. Make your changes

3. Run linting and formatting:

   npm run lint:fix
   npm run format

4. Test your changes:

   npm test
   node bin/api-docs.js endpoints stripe

5. Commit and push:

   git add .
   git commit -m "Add your feature"
   git push origin feature/your-feature

6. Open a pull request

Adding a New Extractor

1. Create a new file in src/extractors/
2. Export an extraction function and error class
3. Add the extractor to the fallback chain in bin/api-docs.js
4. Update tests

Example structure:

export class MyExtractorError extends Error {
  constructor(message, cause) {
    super(message);
    this.name = 'MyExtractorError';
    this.cause = cause;
  }
}

export async function extractFromMySource(url, options = {}) {
  // Implementation
  return {
    spec: openApiSpec,
    format: 'json',
    specInfo: { title, type, version }
  };
}

Releases

Releases are managed via npm run release. This:

1. Bumps version in package.json
2. Creates a git tag
3. Publishes to npm

License

Elastic License 2.0. See LICENSE.