Swagger 2.0 CLI

Features

• Validate Swagger 2.0 APIs in JSON or YAML format
• Supports multi-file APIs via $ref pointers
• Bundle multiple Swagger files into one combined Swagger file
• Built-in HTTP server to serve your REST API — great for testing!

Installation

Install using npm:

npm install -g swagger-cli

Usage

swagger <command> [options] <filename>

Commands:
    validate                        Validates a Swagger API against the Swagger 2.0 schema and spec

    bundle                          Bundles a multi-file Swagger API into a single file

    serve                           Serves a Swagger API via the built-in HTTP REST server

Options:
    -h, --help                      Show help for any command
    -V, --version                   Output the CLI version number
    -d, --debug [filter]            Show debug output, optionally filtered (e.g. "*", "swagger:*", etc.)

Validate an API

The swagger validate command will validate your Swagger API against the Swagger 2.0 schema and the Swagger 2.0 spec to make sure it is fully compliant. The command will exit with a non-zero code if the API is invalid.

swagger validate [options] <filename>

Options:
    --no-schema                     Do NOT validate against the Swagger 2.0 schema

    --no-spec                       Do NOT validate against the Swagger 2.0 spec

Combine Multiple Files

The Swagger 2.0 spec allows you to split your API across multiple files using $ref pointers to reference each file. You can use the swagger bundle command to combine all of those referenced files into a single file, which is useful for distribution or interoperation with other tools.

By default, the swagger bundle command tries to keep the output file size as small as possible, by only embedding each referenced file once. If the same file is referenced multiple times, then any subsequent references are simply modified to point to the single inlined copy of the file. If you want to produce a bundled file without any $ref pointers, then add the --dereference option. This will result in a larger file size, since multiple references to the same file will result in that file being embedded multiple times.

If you don't specify the --output-file option, then the bundled API will be written to stdout, which means you can pipe it to other commands.

swagger bundle [options] <filename>

Options:
    -o, --outfile <filename>        The output file

    -r, --dereference               Fully dereference all $ref pointers

    -j, --swagger-json-schema       Remove any JSON Schema pieces not supported by Swagger's implementation of JSON Schema

    -f, --format <spaces>           Formats the JSON output using the given number of spaces
                                    (the default is 2 spaces)

HTTP REST Server

The swagger serve command serves your REST API via the built-in HTTP server — Swagger Server. Swagger Server automatically provides mock implementations for every operation defined in your Swagger API. You can replace or supplement the mock implementations via Express middleware.

By default, Swagger Server uses an in-memory data store, which means no data will be persisted after the server shuts down. This is great for testing and CI purposes, but if you want to maintain data across sessions, then use the --json option, which will persist the REST resources as JSON files.

NOTE: Swagger Server is still in development, so some functionality is not fully complete yet.

swagger serve [options] <filename>

Options:
    -p, --port <port>               The server port number or socket name

    -j, --json <basedir>            Store REST resources as JSON files under the given directory

Contributing

I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.

Building/Testing

To build/test the project locally on your computer:

1. Clone this repo
   git clone https://github.com/bigstickcarpet/swagger-cli.git

2. Install dependencies
   npm install

3. Run the build script
   npm run build

4. Run the unit tests
   npm run mocha (just the tests)
   npm test (tests + code coverage)

License

Swagger CLI is 100% free and open-source, under the MIT license. Use it however you want.