OpanAPI 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.

GitHub Repo | npm