syroegkin
swagger-markdown
CLI script to turn Swagger/OpenAPI specifications into Markdown files. Supports Swagger 2.0 and OpenAPI 3.0.* formats. OpenAPI 3.1.* is not yet supported.
The version 2.0 is a breaking change. The project was rewritten in typescript.
Along with addressing multiple issues, it is more strict now with the openapi version.
The --force-version flag is now obsolete and will be removed in a future release.
see examples folder
Installation
npm install -g swagger-markdownUsage
swagger-markdown [-h] [-v] -i [-o] [--skip-info]
Options:
-h, --help Show this help message and exit.
-v, --version Show program's version number and exit.
-i , --input Path to the swagger yaml file
-o , --output Path to the resulting md file
--skip-info Skip the title, description, version etc, whatever is in the info block.
--force-version [Deprecated] Set the document version, ignore version provided in the yaml file. Use with caution.
Npx (requires no installation)
npx swagger-markdown -i ./basic-auth.yamlExample
swagger-markdown -i path/to/swagger/file.yamlBy default it will create the new file within the same directory with the same name as swagger file but with .md extension.
So, if swagger file is placed in project/api-doc/swagger.yaml the new file will be created as project/api-doc/swagger.md
You can also use it as a npm script in your package.json:
npm i --save-dev swagger-markdown{
"scripts": {
"md-docs": "swagger-markdown -i path/to/swagger.yaml",
//...
}
}npm run md-docs