OpenAPI Spec Markdown Merger (npm package)

 |  Deliverables

Expand the OpenAPI JSON specification description fields by merging the arbitrary markdown files translated to HTML.

Seamlessly Enrich OpenAPI Docs with External Markdown

Motivation

OpenAPI specifications often suffer from bloated JSON files or fragmented documentation. This tool bridges the gap by:

  • Decoupling docs from code: Store Markdown separately (e.g., in /docs) and inject them into OpenAPI description fields.
  • Improving maintainability: Edit Markdown in dedicated files with version control, previews, and collaboration tools.
  • Enabling dynamic pipelines: Integrate with CI/CD or bundlers (e.g., swagger-cli) for automated doc generation.

Key Features

  • Merge tags: Inject Markdown via {% merge './path/file.md' %} syntax.
  • Flexible integration: CLI and programmatic API (Node.js/TS).
  • Modular architecture: Supports in-memory merges, custom base paths, and granular updates.
  • Sanitized HTML output: Secure by default.
  • TypeScript-native: Full type safety and IDE support.

Technology

  • TypeScript
  • Vitest: TDD, unit tests with V8 coverage
  • ESM module format: Modern JS ecosystem compliance
  • CLI entry: Built with commander for ergonomic CLI use (oas-markdown-merger)
  • Markdown/HTML processing: Uses marked for parsing and isomorphic-dompurify for sanitization
  • Tree traversal: Powered by traverse to walk and modify OpenAPI structures
  • Custom build flow via tsx script runner
  • Linting, changelog generation, and usage verification scripts included

GitHub Repo | npm