API Client Documentation Generator

Automatic generation of Jekyll-compatible documentation for the TypeScript API client.

Files

How it Works

  1. Client Generation: The TypeScript API client is generated using:
    • OpenAPI Generator CLI
    • PowerShell script scripts/generate-api-client.ps1
    • Automatically creates markdown documentation files
  2. Documentation Processing: The Python script:
    • Processes generated markdown files from the client
    • Categorizes files by type (APIs, Models, Requests, Responses, Other)
    • Creates Jekyll-compatible pages with proper front matter
    • Fixes broken navigation links
    • Generates a comprehensive index page
  3. Site Building: Jekyll builds the static site including client documentation
  4. Deployment: Automatically deploys to GitHub Pages

Key Features

Output Structure

docs/api-client/
├── index.md                           # Main index with all categories
├── addressapi.md                      # API endpoint documentation
├── addressresource.md                 # Model documentation
├── addressstorerequest.md             # Request documentation
├── addressstore201response.md         # Response documentation
└── ...

File Naming Convention

Categories

APIs (26 items)

API endpoint documentation including:

Models (24 items)

Data model documentation including:

Requests (39 items)

Request object documentation including:

Responses (48 items)

Response object documentation including:

Other (9 items)

Miscellaneous documentation including:

Configuration

The generator uses configuration defined in generate-client-docs.py:

# Configuration
CLIENT_DOCS_DIR = "api-client/docs"
JEKYLL_CLIENT_DIR = "docs/api-client"
LOG_FILE = "docs/client-docs.log"

The generator automatically fixes common broken links:

Usage

Manual Generation

# Generate the TypeScript client first
# . ./scripts/generate-api-client.ps1

# Generate Jekyll documentation
python docs/generate-client-docs.py

Automated Generation

The client documentation is automatically generated as part of the GitHub Pages workflow:

- name: Generate API Client Documentation
  run: |
    if [ -d "api-client/docs" ]; then
      python docs/generate-client-docs.py
    fi

Integration with GitHub Pages

The generated documentation is automatically included in the GitHub Pages build process:

  1. Client Generation: TypeScript client is generated with documentation
  2. Documentation Processing: Python script processes and categorizes files
  3. Jekyll Build: Jekyll processes the generated markdown files
  4. Deployment: Documentation is available at /api-client/

Error Handling

The generator includes comprehensive error handling:

Logging

All operations are logged to docs/client-docs.log with timestamps and severity levels:

Example Output

Generated pages include:

The main index provides:

This automation ensures that the TypeScript API client documentation is always up-to-date and properly integrated with the main documentation site.