swagger-cli

What is swagger-cli?

The swagger-cli npm package is a command-line tool for working with Swagger and OpenAPI definitions. It provides various functionalities such as validating, bundling, dereferencing, and serving API definitions.

What are swagger-cli's main functionalities?

Validate

This feature allows you to validate your Swagger/OpenAPI definition to ensure it is correctly formatted and adheres to the specification.

swagger-cli validate my-api.yaml

Bundle

This feature bundles multiple Swagger/OpenAPI files into a single file. This is useful for managing large APIs split across multiple files.

swagger-cli bundle my-api.yaml --outfile bundled-api.yaml

Dereference

This feature dereferences $ref pointers in your Swagger/OpenAPI definition, replacing them with the actual content they point to. This can be useful for simplifying the API definition.

swagger-cli dereference my-api.yaml --outfile dereferenced-api.yaml

Serve

This feature serves your Swagger/OpenAPI definition over HTTP, allowing you to view and interact with it using a web browser.

swagger-cli serve my-api.yaml

Other packages similar to swagger-cli

swagger-parser

Swagger Parser is a powerful library for parsing, validating, and dereferencing Swagger and OpenAPI definitions. It offers similar functionalities to swagger-cli but is more focused on being used as a library within Node.js applications rather than a command-line tool.

speccy

Speccy is a command-line tool for working with OpenAPI specifications. It provides features like validation, linting, and bundling. It is similar to swagger-cli but includes additional features like linting to enforce best practices.

README

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

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