Skip to main content

API Overview System

Purpose​

This document explains how API overview pages and descriptions are managed.

Two-Tier Approach​

  1. Basic descriptions in swagger_files/markdown_descriptions/descriptions.json → synced to OpenAPI specs
  2. Rich markdown content in swagger_files/markdown_descriptions/*.md → converted to overview MDX pages

Why Not Inject Into Swagger Before Generation?​

OpenAPI tag.description fields are limited to plain text/basic markdown and cannot use:

  • Docusaurus admonitions (:::note, :::warning)
  • React components
  • Complex formatting
  • Internal links with proper routing

The current approach gives us both OpenAPI compatibility AND documentation flexibility.

File Structure​

swagger_files/
├── v2/{api}.json              # OpenAPI specs with basic tag descriptions
└── markdown_descriptions/
    ├── descriptions.json      # Tag-level descriptions for OpenAPI specs
    └── {api}.md               # Rich markdown for documentation overview pages

Build Process​

  1. Validation & Sync (update-v2-descriptions.js)

    • Validates all APIs have markdown files
    • Syncs basic descriptions to OpenAPI specs

  2. Docusaurus Generation

    • yarn docusaurus gen-api-docs all
    • Generates MDX files from OpenAPI specs

  3. Overview Pages (generate-overview-pages.js)

    • Creates {api}-overview.mdx files from markdown
    • Positioned first in each API category

  4. Post-Processing (update-v2-descriptions.js)

    • Updates titles, labels, frontmatter
    • Injects markdown content into MDX files

Adding a New API​

  1. Create swagger_files/v2/{api}.json
  2. Add entry to swagger_files/markdown_descriptions/descriptions.json
  3. Create swagger_files/markdown_descriptions/{api}.md
  4. Run build: bash rundocs.sh

Scripts​

  • scripts/update-v2-descriptions.js - Main script (validation, sync, MDX updates)
  • scripts/generate-overview-pages.js - Creates overview MDX files
  • scripts/main.js - Build orchestration

Troubleshooting​

"No markdown file found" error: Create {api}.md in markdown_descriptions/

"Orphaned markdown file" warning: Either add the missing OpenAPI spec or remove the markdown file

Overview page not appearing: Clear cache: yarn docusaurus clear and rebuild

Last updated on