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 CLI

Command-line tool to parse, validate, and host Swagger-based REST APIs

Alpha Code!
Swagger CLI is still being written. It's not ready to use yet. Check back later, once we release v1.0.0

Features

• Parse and 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!
• Fully-functional mocks for every operation in your API, including data persistence — great for POCs and demos!

Installation

Install using npm. Install it globally (using the -g flag) to run it from any terminal window.

npm install -g swagger-cli

Usage

swagger <command> [options] <filename>

Commands:
    validate        Parses and validates a Swagger file
    
    dereference     Dereferences all $ref pointers in a Swagger file
    
    bundle          Bundles multiple Swagger files into a single file
    
    serve           Serves a Swagger file via a built-in HTTP REST server
    
Options:
    -h, --help      Show help for any command
    -v, --version   Output the CLI version number

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.