Exciting news!Announcing our $4.6M Series Seed. Learn more
Log in


Package Overview
File Explorer

Advanced tools


Convert OpenAPI spec to Markdown files.


Version published
Yearly downloads
increased by4451.08%

Weekly downloads



OpenAPI3 to Markdown converter

Travis Build Status GitHub Workflow Status npm npm Coveralls

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.



yarn add @synx-ai/oas3-mdx


npm install @synx-ai/oas3-mdx

Basic usage


Usage: oas3-mdx --specs [file] --target [target path] --templates [template path] --snippets [string with targets] Options: --version Show version number [boolean] -s, --spec OpenAPI specification [required] -o, --target target build path [default: "./build"] -t, --templates templates path [default: "./templates"] -c, --snippets comma separated targets [default: "shell"] -e, --extension output extension [default: "mdx"] --help Show help


const convert = require('@synx-ai/oas3-mdx').default; // optional arguments are expected as an object, ie: convert('./example/petstore.json' /*, { outPath: 'my_path' }*/);


OptionCLI argumentJavaScript parameterDefault
OpenAPI spec--specspecFileNone
Target build dir--targetoutPath./build
Templates dir--templatestemplatesPath./templates
Snippet targets--snipettssnippetTargets["shell"]
Prettier parser--parserprettierParsermdx
Output extension--extensionextensionmdx

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

Valid Snippet Targets

Currently, OpenAPI Snippet supports the following targets from HTTP Snippet library:

  • c_libcurl (default)
  • csharp_restsharp (default)
  • go_native (default)
  • java_okhttp
  • java_unirest (default)
  • javascript_jquery
  • javascript_xhr (default)
  • node_native (default)
  • node_request
  • node_unirest
  • objc_nsurlsession (default)
  • ocaml_cohttp (default)
  • php_curl (default)
  • php_http1
  • php_http2
  • python_python3 (default)
  • python_requests
  • ruby_native (default)
  • shell_curl (default)
  • shell_httpie
  • shell_wget
  • swift_nsurlsession (default)

Prettier Parser

For the parser, while mdx or markdown are suggested, you can use anything supported by Prettier.

### Custom Tags on Schema

  • x-docgenIgnore: at method level to ignore output generation, for example:
{ ... "paths": { "/pet": { "put": { // this method will be ignored "x-docgenIgnore": true, "summary": "Update an existing pet", ... } } } }


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, example:

<!-- prettier-ignore-start --> <Tabs defaultValue="{{someVar}}" values={[ {{#each content}} { label: "{{@key}}", value: "{{@key}}" }, {{/each}} ]}> <!-- prettier-ignore-end -->

Using partials

In your templatesPath create a dir called partials every single file with .hdb extension within its subdirs will be loaded as partial, using the filename as partial name. Example:

A file named partials/quote.hdb with the following code, will create a quote partial.


This partial can be used in your templates as follows:

{{>quote "This text will be quoted."}}

Using helpers

In your templatesPath create a dir called helpers every single file with .js extension within its subdirs will be loaded as a helper, using the filename as the helper name. Example:

A file named partials/loud.js with the following code, will create a load helper.

// the script should export an anonymous function in order to execute // you can use many parameters as needed exports.default = function (text) { return text.toUpperCase() }

This helper can be used in your templates as follows:

{{loud "This text will be uppercased."}}


  • Most common errors happens due a malformed file, to validate and lint your spec for possible errors check Speccy.
  • If your specification has multiple paths which map to the same OpenAPI path, you can should set "x-hasEquivalentPaths": true, on the root object, example:
{ "openapi": "3.0.2", "x-hasEquivalentPaths": true, "info": { ... } ... }



PR's are more than welcome and highly appreciated.



What is @synx-ai&#x2F;oas3-mdx?

Convert OpenAPI spec to Markdown files.

Is @synx-ai&#x2F;oas3-mdx popular?

The npm package @synx-ai&#x2F;oas3-mdx receives a total of 145 weekly downloads. As such, @synx-ai&#x2F;oas3-mdx popularity was classified as not popular.

Is @synx-ai&#x2F;oas3-mdx well maintained?

We found that @synx-ai&#x2F;oas3-mdx demonstrated a healthy version release cadence and project activity. It has 1 open source maintainer collaborating on the project.

Last updated on 25 Sep 2021


Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc