{"id":15091482,"url":"https://github.com/synx-ai/oas3-mdx","last_synced_at":"2025-04-12T06:32:49.256Z","repository":{"id":46800994,"uuid":"341718919","full_name":"synx-ai/oas3-mdx","owner":"synx-ai","description":"OpenAPI Spec to Markdown","archived":false,"fork":false,"pushed_at":"2021-09-25T08:39:35.000Z","size":794,"stargazers_count":9,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-31T10:51:27.663Z","etag":null,"topics":["docgen","documentation","markdown","mdx","oas","oas3","openapi"],"latest_commit_sha":null,"homepage":"https://synx-ai.github.io/oas3-mdx","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/synx-ai.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-23T23:25:22.000Z","updated_at":"2024-07-15T22:06:28.000Z","dependencies_parsed_at":"2022-08-22T23:20:53.180Z","dependency_job_id":null,"html_url":"https://github.com/synx-ai/oas3-mdx","commit_stats":null,"previous_names":["synx-ai/openapi2md"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synx-ai%2Foas3-mdx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synx-ai%2Foas3-mdx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synx-ai%2Foas3-mdx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synx-ai%2Foas3-mdx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/synx-ai","download_url":"https://codeload.github.com/synx-ai/oas3-mdx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223502361,"owners_count":17155938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docgen","documentation","markdown","mdx","oas","oas3","openapi"],"created_at":"2024-09-25T10:41:19.743Z","updated_at":"2024-11-07T11:05:13.099Z","avatar_url":"https://github.com/synx-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI3 to Markdown converter\n[![Travis Build Status](https://img.shields.io/travis/synx-ai/oas3-mdx?logo=travis)](https://travis-ci.com/synx-ai/oas3-mdx) [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/synx-ai/oas3-mdx/Node.js%20Package?label=package\u0026logo=github)](https://github.com/synx-ai/oas3-mdx/actions/workflows/package.yml) [![npm](https://img.shields.io/npm/v/@synx-ai/oas3-mdx?logo=npm)](https://www.npmjs.com/package/@synx-ai/oas3-mdx) [![npm](https://img.shields.io/npm/dw/@synx-ai/oas3-mdx?logo=npm)](https://www.npmjs.com/package/@synx-ai/oas3-mdx) [![Coveralls](https://img.shields.io/coveralls/github/synx-ai/oas3-mdx?logo=coveralls)](https://coveralls.io/github/synx-ai/oas3-mdx)\n\n\nConvert 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.\n\n[**Handlebars**](https://handlebarsjs.com/) is used to provide fully configurable templating support.\n\n\n## Installation\n\n### yarn\n```console\nyarn add @synx-ai/oas3-mdx\n```\n\n### npm\n```console\nnpm install @synx-ai/oas3-mdx\n```\n\n\n## Basic usage\n\n### CLI\n```console\nUsage: oas3-mdx --specs [file] --target [target path] --templates [template path] --snippets [string with targets]\n\nOptions:\n      --version   Show version number                         [boolean]\n  -s, --spec      OpenAPI specification                      [required]\n  -o, --target    target build path                [default: \"./build\"]\n  -t, --templates templates path               [default: \"./templates\"]\n  -c, --snippets  comma separated targets            [default: \"shell\"]\n  -e, --extension output extension                     [default: \"mdx\"]\n      --help      Show help\n```\n\n### JavaScript\n```javascript\nconst convert = require('@synx-ai/oas3-mdx').default;\n\n// optional arguments are expected as an object, ie:\nconvert('./example/petstore.json' /*, { outPath: 'my_path' }*/);\n```\n\n### Options\n\n| Option             | CLI argument | JavaScript parameter | Default       |\n| ------------------ | ------------ | -------------------- | ------------- |\n| `OpenAPI spec`     | --spec       | specFile             | _None_        |\n| `Target build dir` | --target     | outPath              | `./build`     |\n| `Templates dir`    | --templates  | templatesPath        | `./templates` |\n| `Snippet targets`  | --snipetts   | snippetTargets       | `[\"shell\"]`   |\n| `Prettier parser`  | --parser     | prettierParser       | `mdx`         |\n| `Output extension` | --extension  | extension            | `mdx`         |\n\nThe tool will try to load the `--templates` relative to current working path first, then will fallback to library path.\n\n### Valid Snippet Targets\nCurrently, OpenAPI Snippet supports the following targets from [HTTP Snippet](https://github.com/Kong/httpsnippet) library:\n\n* `c_libcurl` (default)\n* `csharp_restsharp` (default)\n* `go_native` (default)\n* `java_okhttp`\n* `java_unirest` (default)\n* `javascript_jquery`\n* `javascript_xhr` (default)\n* `node_native` (default)\n* `node_request`\n* `node_unirest`\n* `objc_nsurlsession` (default)\n* `ocaml_cohttp` (default)\n* `php_curl` (default)\n* `php_http1`\n* `php_http2`\n* `python_python3` (default)\n* `python_requests`\n* `ruby_native` (default)\n* `shell_curl` (default)\n* `shell_httpie`\n* `shell_wget`\n* `swift_nsurlsession` (default)\n\n### Prettier Parser\n\nFor the parser, while `mdx` or `markdown` are suggested, you can use anything supported by [Prettier](https://prettier.io/docs/en/options.html#parser).\n\n\n### Custom Tags on Schema\n\n- `x-docgenIgnore`: at method level to ignore output generation, for example:\n\n```js\n{\n  ...\n  \"paths\": {\n    \"/pet\": {\n      \"put\": { // this method will be ignored\n        \"x-docgenIgnore\": true,\n        \"summary\": \"Update an existing pet\",\n        ...\n      }\n    }\n  }\n}\n```\n\n### Templates\n\nFor 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.\n\nPlease note that before saving, prettify will be executed to format the output, you can disable it using the `\u003c!-- prettier-ignore-start --\u003e` tag, example:\n\n```html\n\u003c!-- prettier-ignore-start --\u003e\n\n\u003cTabs defaultValue=\"{{someVar}}\" values={[\n{{#each content}}\n  { label: \"{{@key}}\", value: \"{{@key}}\" },\n{{/each}}\n]}\u003e\n\n\u003c!-- prettier-ignore-end --\u003e\n```\n\n### Using partials\n\nIn 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:\n\nA file named `partials/quote.hdb` with the following code, will create a `quote` partial.\n\n```\n\u003e{{text}}\n```\n\nThis partial can be used in your templates as follows:\n\n```markdown\n{{\u003equote \"This text will be quoted.\"}}\n```\n\n### Using helpers\n\nIn 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:\n\nA file named `partials/loud.js` with the following code, will create a `load` helper.\n\n```javascript\n// the script should export an anonymous function in order to execute\n// you can use many parameters as needed\nexports.default = function (text) {\n  return text.toUpperCase()\n}\n```\n\nThis helper can be used in your templates as follows:\n\n```markdown\n{{loud \"This text will be uppercased.\"}}\n```\n\n\n## Troubleshooting\n- Most common errors happens due a malformed file, to validate and lint your spec for possible errors check [Speccy](https://github.com/wework/speccy).\n- 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:\n\n```javascript\n{\n  \"openapi\": \"3.0.2\",\n  \"x-hasEquivalentPaths\": true,\n  \"info\": {\n    ...\n  }\n  ...\n}  \n```\n\n## Roadmap\n- [X] Create a cli.js file to execute commands using yarn or npm\n- [X] Add more configurations (ie: custom templates)\n- [X] ~MDX templating support for platform that supports **React** components.~ Removed as it can be customized from current templates.\n- [ ] Add schemas and general info rendering.\n\n## Contribute\nPR's are more than welcome and highly appreciated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynx-ai%2Foas3-mdx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsynx-ai%2Foas3-mdx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynx-ai%2Foas3-mdx/lists"}