Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/synx-ai/oas3-mdx
OpenAPI Spec to Markdown
https://github.com/synx-ai/oas3-mdx
docgen documentation markdown mdx oas oas3 openapi
Last synced: 2 days ago
JSON representation
OpenAPI Spec to Markdown
- Host: GitHub
- URL: https://github.com/synx-ai/oas3-mdx
- Owner: synx-ai
- License: mit
- Created: 2021-02-23T23:25:22.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2021-09-25T08:39:35.000Z (about 3 years ago)
- Last Synced: 2024-09-20T18:31:54.757Z (7 days ago)
- Topics: docgen, documentation, markdown, mdx, oas, oas3, openapi
- Language: TypeScript
- Homepage: https://synx-ai.github.io/oas3-mdx
- Size: 775 KB
- Stars: 9
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI3 to Markdown converter
[](https://travis-ci.com/synx-ai/oas3-mdx) [](https://github.com/synx-ai/oas3-mdx/actions/workflows/package.yml) [](https://www.npmjs.com/package/@synx-ai/oas3-mdx) [](https://www.npmjs.com/package/@synx-ai/oas3-mdx) [](https://coveralls.io/github/synx-ai/oas3-mdx)
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**](https://handlebarsjs.com/) is used to provide fully configurable templating support.
## Installation
### yarn
```console
yarn add @synx-ai/oas3-mdx
```
### npm
```console
npm install @synx-ai/oas3-mdx
```
## Basic usage
### CLI
```console
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
```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](https://github.com/Kong/httpsnippet) 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](https://prettier.io/docs/en/options.html#parser).
### Custom Tags on Schema
- `x-docgenIgnore`: at method level to ignore output generation, for example:
```js
{
...
"paths": {
"/pet": {
"put": { // this method will be ignored
"x-docgenIgnore": true,
"summary": "Update an existing pet",
...
}
}
}
}
```
### Templates
For every [**operation**](https://swagger.io/docs/specification/paths-and-operations/) 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 `` tag, example:
```html
```
### 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:
```markdown
{{>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.
```javascript
// 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:
```markdown
{{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](https://github.com/wework/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:
```javascript
{
"openapi": "3.0.2",
"x-hasEquivalentPaths": true,
"info": {
...
}
...
}
```
## Roadmap
- [X] Create a cli.js file to execute commands using yarn or npm
- [X] Add more configurations (ie: custom templates)
- [X] ~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.