swagger-cli validate: Validate and Bundle OpenAPI
swagger-cli validate parses an API definition, resolves its $refs, and reports schema or reference errors with a non-zero exit code.
swagger-cli (a thin wrapper over swagger-parser) is a fast, dependency-light way to fail a build on a broken OpenAPI file before any heavier tooling runs.
What it does
The validate command reads the document, resolves every $ref, and checks it against the OpenAPI/Swagger schema plus semantic rules (duplicate operationIds, missing definitions). The bundle command merges multi-file specs.
Common usage
swagger-cli validate openapi.yaml
# bundle a multi-file spec into one file
swagger-cli bundle openapi.yaml -o dist/openapi.json -r
# note: modern package is @apidevtools/swagger-cliOptions
| Flag | What it does |
|---|---|
| validate <file> | Validate schema and resolve references |
| bundle <file> | Merge external $refs into one document |
| -o, --outfile <file> | Output path for bundle |
| -r, --dereference | Fully dereference instead of keeping internal $refs |
| -f, --format <n> | JSON indentation spaces for bundle output |
| -t, --type <yaml|json> | Output format for bundle |
In CI
Run swagger-cli validate as the first, cheap gate in the API job; it fails fast on structural errors before you spend time on lint, codegen, or docs. Then swagger-cli bundle to produce the single file downstream steps consume.
Common errors in CI
A failure prints <file> is not a valid API definition followed by the specific problem, e.g. Token "Foo" does not exist. for a bad $ref, or Missing $ref pointer .... Error resolving $ref pointer ... ENOENT means a missing referenced file. Data does not match any schemas from "oneOf" indicates a structural violation of the OpenAPI schema.