readme.md

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/oas3-mdx

npm

npm install @synx-ai/oas3-mdx

Basic usage

CLI

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

JavaScript

const convert = require('@synx-ai/oas3-mdx').default;

// optional arguments are expected as an object, ie:
convert('./example/petstore.json' /*, { outPath: 'my_path' }*/);

Options

Option	CLI argument	JavaScript parameter	Default
OpenAPI spec	--spec	specFile	None
Target build dir	--target	outPath	./build
Templates dir	--templates	templatesPath	./templates
Snippet targets	--snipetts	snippetTargets	["shell"]
Prettier parser	--parser	prettierParser	mdx
Output extension	--extension	extension	mdx

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",
        ...
      }
    }
  }
}

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

>{{text}}

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."}}

Troubleshooting

• 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": {
    ...
  }
  ...
}  

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.