Skip to content

Latest commit

 

History

History
108 lines (70 loc) · 4.5 KB

README.md

File metadata and controls

108 lines (70 loc) · 4.5 KB
Raw

Swagger 2.0 CLI

Build Status Dependencies Codacy Score Inline docs

npm License

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

Related Projects

Installation

Install using npm:

npm install -g swagger-cli

Usage

swagger-cli <command> [options] <file>

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

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-cli 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-cli validate [options] <file>

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

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

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-cli 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-cli 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-cli bundle [options] <file>

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

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

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

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 tests
    npm test

License

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