@apidevtools/swagger-cli

What is @apidevtools/swagger-cli?

@apidevtools/swagger-cli is a command-line tool for working with Swagger and OpenAPI definitions. It allows you to bundle, dereference, validate, and serve your API definitions, making it easier to manage and deploy your API documentation.

What are @apidevtools/swagger-cli's main functionalities?

Bundle

The bundle command combines all the files referenced in your Swagger/OpenAPI definition into a single file. This is useful for simplifying the distribution and deployment of your API documentation.

swagger-cli bundle path/to/api.yaml -o bundled.yaml

Dereference

The dereference command replaces all $ref pointers in your Swagger/OpenAPI definition with the actual referenced content. This results in a single, fully-resolved API definition file.

swagger-cli dereference path/to/api.yaml -o dereferenced.yaml

Validate

The validate command checks your Swagger/OpenAPI definition for errors and ensures it adheres to the specification. This helps catch issues early in the development process.

swagger-cli validate path/to/api.yaml

Serve

The serve command starts a local HTTP server to serve your Swagger/OpenAPI definition. This is useful for quickly previewing your API documentation in a web browser.

swagger-cli serve path/to/api.yaml

Other packages similar to @apidevtools/swagger-cli

swagger-parser

swagger-parser is a powerful library for parsing, validating, and dereferencing Swagger and OpenAPI definitions. It provides similar functionality to @apidevtools/swagger-cli but is designed to be used as a library within your Node.js applications rather than a command-line tool.

swagger-jsdoc

swagger-jsdoc is a library that generates Swagger/OpenAPI documentation from JSDoc comments in your code. It focuses on creating API documentation from your existing codebase, whereas @apidevtools/swagger-cli is more about managing and validating existing Swagger/OpenAPI definition files.

README

Swagger/OpenAPI CLI

Features

• Validate Swagger/OpenAPI files in JSON or YAML format
• Supports multi-file API definitions via $ref pointers
• Bundle multiple Swagger/OpenAPI files into one combined file

Related Projects

• Swagger Parser
• Swagger Express Middleware

Installation

Install using npm:

npm install -g @apidevtools/swagger-cli

Usage

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

Commands:
    validate                Validates an API definition in Swagger 2.0 or OpenAPI 3.0 format

    bundle                  Bundles a multi-file API definition 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/OpenAPI definition against the Swagger 2.0 schema or OpenAPI 3.0 Schema. It also performs additional validations against the specification, which will catch some things that aren't covered by the schema, such as duplicate parameters, invalid MIME types, etc.

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/OpenAPI JSON schema

    --no-spec               Do NOT validate against the Swagger/OpenAPI specification

Git pre-commit hook

There is a useful Python tool called pre-commit that can be used to execute a wide suite of pre-commit checks. The swagger-cli validate command can be integrated as part of a git pre-commit hook by adding the following configuration to the repos entry of an existing .pre-commit-config.yaml file.

-   repo: https://github.com/APIDevTools/swagger-cli
    rev: v2.2.1
    hooks:
    - id: swagger-validation
      args: ["validate", "<path to root swagger>"]

The intention is to point to single root swagger that references multiple swagger definitions. The above hook will execute the swagger-cli validation against the root swagger anytime that a file matching the pattern .*swagger.*\.(json|yaml|yml) is modified. Any failures in this validation will prevent the git commit from being processed.

Combine Multiple Files

The Swagger and OpenAPI specs allows you to split your API definition 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.

The result of this method by default is written as JSON. It can be changed to YAML with the --type option, by passing the yaml value.

swagger-cli bundle [options] <file>

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

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

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

    -t, --type <filetype>       Defines the output file type. The valid values are: json, yaml
                                (the default is JSON)

    -w, --wrap <column>         Set the line length for YAML strings
                                (the default is no wrapping)

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

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤