@andrezz/openapimd

Convert OpenAPI specifications (JSON or YAML) into clean Markdown documentation.

openapimd is a small CLI and library that reads an OpenAPI 3.x document from a local file or a URL and renders it as Markdown. It supports two output templates: a single self-contained file, or a structured set of files with an index.

Requirements

• Node.js >= 18

Features

• Read OpenAPI specs from local files or URLs (http/https).
• Accept JSON and YAML inputs (format auto-detected from extension or content type).
• Two output templates:
  • single (default) — everything in one Markdown file.
  • document — an index.md plus one file per tag under spec/*.md and a spec/schemas.md.
• Configurable output path (defaults to the current directory).
• Full TypeScript support with a public library API.
• Cross-platform, with a single runtime dependency (yaml).

Installation

The package is published to the public npm registry, so it can be installed with no extra configuration:

npm install @andrezz/openapimd

Global install (CLI)

npm install --global @andrezz/openapimd

After a global install, the openapimd command is available on your PATH.

Run without installing

npx @andrezz/openapimd openapi.json

Usage

Command line

openapimd <input> [options]

<input> is a path to a local file or a URL.

| Option | Description | | --- | --- | | -o, --output <path> | Output file (single template) or directory (document template). Defaults to the current directory. | | -t, --template <type> | Rendering template: single (default) or document. | | -h, --help | Show help. | | -V, --version | Show the version. |

Examples

Convert a local JSON file into ./openapi.md:

openapimd openapi.json

Convert a remote YAML file into a specific directory:

openapimd https://api.example.com/openapi.yaml -o ./docs

Write to a custom file name (single template):

openapimd openapi.json -o ./docs/api.md

Generate the multi-file documentation:

openapimd openapi.json -t document -o ./docs

The document template produces:

docs/
├── index.md          # overview + endpoint index
└── spec/
    ├── <tag>.md      # one file per tag (or default.md for untagged operations)
    └── schemas.md    # data models

Programmatic API

import { convert } from '@andrezz/openapimd';

const result = await convert('openapi.json', {
  output: './docs',
  template: 'document',
});

console.log(result.outputDir); // absolute output directory
console.log(result.files);     // absolute paths of the generated files

Development

# Install dependencies
npm install

# Run the test suite
npm test

# Run tests with coverage (threshold is 80%)
npm run test:coverage

# Compile to dist/
npm run build

# Try the CLI locally
node dist/cli.js openapi.json

Contributing

Issues and pull requests are welcome. See the issue tracker to get started.

License

MIT © andrezz