@synx-ai/oas3-mdx

OpenAPI3 to Markdown converter

Convert OpenAPI v3 spec into a directory of markdown files based on your spec paths. The purpose of this tool is to boost documentation generation and seamlessly integrate them into static site generators.

Handlebars is used to provide fully configurable templating support.

Installation

yarn

yarn add @synx-ai/openapi2md

npm

npm install @synx-ai/openapi2md

Basic usage

Options

Option	CLI argument	JavaScript parameter	Default
OpenAPI spec	--spec	specFile	None
Target build dir	--target	outPath	./build
Templates dir	--templates	templatePath	./templates

The tool will try to load the --templates relative to current working path first, then will fallback to library path.

CLI

Usage: openapi2md --specs [file] --target [target path] --templates [template path]

Options:
      --version   Show version number                         [boolean]
  -s, --spec      OpenAPI specification                      [required]
  -o, --target    target build path                [default: "./build"]
  -t, --template  templates paths              [default: "./templates"]
      --help      Show help

JavaScript

const convert = require('openapi2md').default;

convert('./example/petstore.json', './build');

Templates

For every operation in paths, object with all references resolved will be passed to templates/path.hdb, please refer to default template for an example in how to use it.

Please note that before saving, prettify will be executed to format the output, you can disable it using the <!-- prettier-ignore-start --> tag, exmaple:

<!-- prettier-ignore-start -->

<Tabs defaultValue="{{someVar}}" values={[
{{#each content}}
  { label: "{{@key}}", value: "{{@key}}" },
{{/each}}
]}>

<!-- prettier-ignore-end -->

Roadmap

• Create a cli.js file to execute commands using yarn or npm
• Add more configurations (ie: custom templates)
• MDX templating support for platform that supports React components. Removed as it can be customized from current templates.
• Add schemas and general info rendering.

Contribute

PR's are more than welcome and highly appreciated.