Overview System Refactoring Notes

Changes Made

Consolidated Scripts

• Removed: scripts/validate-descriptions.js (standalone)
• Removed: scripts/sync-tag-descriptions.js (standalone)
• Removed: scripts/lib/mdx-content-injector.js (unused library)
• Enhanced: scripts/update-v2-descriptions.js now includes:
  • validateDescriptions() - Validates all APIs have markdown files
  • syncTagDescriptions() - Syncs basic descriptions to OpenAPI specs
  • mapAndUpdateDescriptions() - Existing MDX post-processing

Build Integration

• scripts/main.js step 2/10 now calls validation and sync from consolidated script
• Validation and sync run automatically during every build

Documentation

• Created: docs/internal/overview-system.md - System documentation
• Created: docs/internal/refactoring-notes.md - This file
• Removed: Redundant README files from scripts and markdown_descriptions

Why This Approach?

After evaluating whether to inject content into swagger files before generation vs. after:

Decision: Keep current approach (post-generation injection)

Reasoning:

• OpenAPI tag descriptions are limited to plain text
• Rich markdown in separate files allows:
  • Docusaurus admonitions (:::note, :::warning)
  • React components
  • Complex formatting
  • Better maintainability

Key Points

1. Two-tier system: Basic descriptions in OpenAPI specs + rich markdown for docs
2. Validation built-in: Every build checks for completeness
3. One script: All description management in update-v2-descriptions.js
4. Clean structure: Documentation in docs/internal/, not scattered

Future Work

If further improvements needed:

• Consider refactoring old MDX manipulation code in update-v2-descriptions.js
• Add unit tests for validation/sync functions
• Create pre-commit hook for validation