Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


npm circle ci

CLI script to turn swagger yaml into markdown files. Supports swagger 2.0 format only

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. In case if version 3 is provided, the application will throw an error. The 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. As soon as v3 support will be added, the flag will be removed.

see examples folder


npm install -g swagger-markdown


swagger-markdown [-h] [-v] -i [-o] [--skip-info]

  -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 Set the document version, ignore version provided in the yaml file

Npx (requires no installation)

npx swagger-markdown -i ./basic-auth.yaml


swagger-markdown -i path/to/swagger/file.yaml

By 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/

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