swagger-markdown

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

Installation

npm install -g swagger-markdown

Usage

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

Npx (requires no installation)

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

Example

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

Related

• swagger-markdown-ui (source)