{"id":13496398,"url":"https://github.com/syroegkin/swagger-markdown","last_synced_at":"2025-04-12T18:54:31.079Z","repository":{"id":10364062,"uuid":"65502239","full_name":"syroegkin/swagger-markdown","owner":"syroegkin","description":"swagger to markdown transpiler","archived":false,"fork":false,"pushed_at":"2024-03-26T08:29:02.000Z","size":2409,"stargazers_count":228,"open_issues_count":5,"forks_count":85,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-27T09:42:23.893Z","etag":null,"topics":["javascript","js","markdown","node","nodejs","openapi","swagger"],"latest_commit_sha":null,"homepage":"","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/syroegkin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-11T21:19:43.000Z","updated_at":"2024-06-16T18:03:00.981Z","dependencies_parsed_at":"2024-01-16T09:02:26.999Z","dependency_job_id":"3898d130-0fc2-466a-b931-f1166a20240a","html_url":"https://github.com/syroegkin/swagger-markdown","commit_stats":{"total_commits":314,"total_committers":18,"mean_commits":"17.444444444444443","dds":0.5254777070063694,"last_synced_commit":"a6f08f6eba107f62dcd17d09d59f9703da5bf9ee"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syroegkin%2Fswagger-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syroegkin%2Fswagger-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syroegkin%2Fswagger-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syroegkin%2Fswagger-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syroegkin","download_url":"https://codeload.github.com/syroegkin/swagger-markdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618262,"owners_count":21134200,"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":["javascript","js","markdown","node","nodejs","openapi","swagger"],"created_at":"2024-07-31T19:01:47.382Z","updated_at":"2025-04-12T18:54:31.047Z","avatar_url":"https://github.com/syroegkin.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# swagger-markdown\n\n[![npm][npm-image]][npm-url] [![circle ci][circleci-image]][circleci-url]\n\nCLI script to turn swagger yaml into markdown files.\nSupports swagger 2.0 format only\n\nThe version 2.0 is a breaking change. The project was rewritten in typescript.\nAlong with addressing multiple issues, it is more strict now with the openapi version. \nIn case if version 3 is provided, the application will throw an error.\nThe support of v3 is at the roadmap, although it is possible to overcome this restriction by using --force-version flag: `--force-version 2`. It will process v3 documents as it is v2, although it may fail and it may generate the markdown with errors.\nAs soon as v3 support will be added, the flag will be removed.\n\nsee [examples](https://github.com/syroegkin/swagger-markdown/tree/master/examples) folder\n\n### Installation\n\n```bash\nnpm install -g swagger-markdown\n```\n\n### Usage\n\n```\nswagger-markdown [-h] [-v] -i [-o] [--skip-info]\n\nOptions:\n  -h, --help      Show this help message and exit.\n  -v, --version   Show program's version number and exit.\n  -i , --input    Path to the swagger yaml file\n  -o , --output   Path to the resulting md file\n  --skip-info     Skip the title, description, version etc, whatever is in the info block.\n  --force-version Set the document version, ignore version provided in the yaml file\n\n```\n\n### Npx (requires no installation)\n\n```bash\nnpx swagger-markdown -i ./basic-auth.yaml\n```\n\n#### Example\n\n```bash\nswagger-markdown -i path/to/swagger/file.yaml\n```\n\nBy default it will create the new file within the same directory with the same name as swagger file but with .md extension.\nSo, if swagger file is placed in `project/api-doc/swagger.yaml` the new file will be created as `project/api-doc/swagger.md`\n\nYou can also use it as a npm script in your package.json:\n\n```bash\nnpm i --save-dev swagger-markdown\n```\n\n```json\n{\n    \"scripts\": {\n        \"md-docs\": \"swagger-markdown -i path/to/swagger.yaml\",\n        //...\n    }\n}\n```\n\n```bash\nnpm run md-docs\n```\n\n### Related\n\n* [swagger-markdown-ui](https://swagger-markdown-ui.netlify.app/) ([source](https://github.com/shaun-chiang/swagger-markdown-ui))\n\n[npm-url]: https://www.npmjs.com/package/swagger-markdown\n[npm-image]: https://img.shields.io/npm/v/swagger-markdown.svg\n\n[circleci-url]: https://circleci.com/gh/syroegkin/swagger-markdown/tree/master\n[circleci-image]: https://img.shields.io/circleci/project/syroegkin/swagger-markdown.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyroegkin%2Fswagger-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyroegkin%2Fswagger-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyroegkin%2Fswagger-markdown/lists"}