{"id":15091216,"url":"https://github.com/apidevtools/swagger-cli","last_synced_at":"2025-10-06T10:31:02.338Z","repository":{"id":33034776,"uuid":"36670476","full_name":"APIDevTools/swagger-cli","owner":"APIDevTools","description":"Swagger 2.0 and OpenAPI 3.0 command-line tool","archived":true,"fork":false,"pushed_at":"2023-11-15T11:23:27.000Z","size":432,"stargazers_count":517,"open_issues_count":51,"forks_count":68,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-29T21:10:26.764Z","etag":null,"topics":["cli","javascript","json-schema","nodejs","open-api","parser","swagger","validation","validator"],"latest_commit_sha":null,"homepage":"https://apitools.dev/swagger-cli","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/APIDevTools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-06-01T15:36:25.000Z","updated_at":"2024-10-23T17:45:28.000Z","dependencies_parsed_at":"2023-11-21T21:02:59.902Z","dependency_job_id":"4b96c760-3327-4cfd-ad29-526c892b8e32","html_url":"https://github.com/APIDevTools/swagger-cli","commit_stats":{"total_commits":192,"total_committers":8,"mean_commits":24.0,"dds":"0.16145833333333337","last_synced_commit":"3657ea9d71b5229ec0c554adfb9094d282f4dc8b"},"previous_names":["bigstickcarpet/swagger-cli"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fswagger-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fswagger-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fswagger-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APIDevTools%2Fswagger-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/APIDevTools","download_url":"https://codeload.github.com/APIDevTools/swagger-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235519935,"owners_count":19003201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","javascript","json-schema","nodejs","open-api","parser","swagger","validation","validator"],"created_at":"2024-09-25T10:36:30.273Z","updated_at":"2025-10-06T10:30:56.986Z","avatar_url":"https://github.com/APIDevTools.png","language":"JavaScript","readme":"Swagger/OpenAPI CLI\n============================\n\n[![npm](https://img.shields.io/npm/v/@apidevtools/swagger-cli.svg)](https://www.npmjs.com/package/@apidevtools/swagger-cli)\n[![License](https://img.shields.io/npm/l/@apidevtools/swagger-cli.svg)](LICENSE)\n[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/APIDevTools/swagger-cli)\n\n\n\u003e ⚠️ Swagger CLI has been deprecated, due to the maintenance burnden of trying to keep up with expectations of a huge userbase with little to no pull requests or support. [Redocly CLI](https://redocly.com/redocly-cli/) covers all of the same functionality, and has more advanced linting with custom rules, and we highly recommend using that instead. They have conveniently provided a [migration guide](https://redocly.com/docs/cli/guides/migrate-from-swagger-cli/) for existing Swagger CLI users. Read the review of [Redocly CLI from APIs You Won't Hate](https://apisyouwonthate.com/blog/redocly-cli/).\n\nFeatures\n--------------------------\n- Validate Swagger/OpenAPI files in **JSON or YAML** format\n- Supports multi-file API definitions via `$ref` pointers\n- Bundle multiple Swagger/OpenAPI files into one combined file\n\n\n\nRelated Projects\n--------------------------\n- [Swagger Parser](https://github.com/APIDevTools/swagger-parser)\n- [Swagger Express Middleware](https://github.com/APIDevTools/swagger-express-middleware)\n\n\n\nInstallation\n--------------------------\nInstall using [npm](https://docs.npmjs.com/about-npm/):\n\n```bash\nnpm install -g @apidevtools/swagger-cli\n```\n\n\n\nUsage\n--------------------------\n\n```\nswagger-cli \u003ccommand\u003e [options] \u003cfile\u003e\n\nCommands:\n    validate                Validates an API definition in Swagger 2.0 or OpenAPI 3.0 format\n\n    bundle                  Bundles a multi-file API definition into a single file\n\nOptions:\n    -h, --help              Show help for any command\n    -v, --version           Output the CLI version number\n    -d, --debug [filter]    Show debug output, optionally filtered (e.g. \"*\", \"swagger:*\", etc.)\n```\n\n\n### Validate an API\n\nThe `swagger-cli validate` command will validate your Swagger/OpenAPI definition against the [Swagger 2.0 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json) or [OpenAPI 3.0 Schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.json).  It also performs additional validations against the [specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md), which will catch some things that aren't covered by the schema, such as duplicate parameters, invalid MIME types, etc.\n\nThe command will exit with a non-zero code if the API is invalid.\n\n```\nswagger-cli validate [options] \u003cfile\u003e\n\nOptions:\n    --no-schema             Do NOT validate against the Swagger/OpenAPI JSON schema\n\n    --no-spec               Do NOT validate against the Swagger/OpenAPI specification\n```\n\n#### Git pre-commit hook\n\nThere is a useful Python tool called [pre-commit](https://pre-commit.com/) 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.\n\n```\n-   repo: https://github.com/APIDevTools/swagger-cli\n    rev: v2.2.1\n    hooks:\n    - id: swagger-validation\n      args: [\"validate\", \"\u003cpath to root swagger\u003e\"]\n```\n\nThe 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.\n\n### Combine Multiple Files\n\nThe Swagger and OpenAPI specs allows you to split your API definition across multiple files using [`$ref` pointers](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#reference-object) 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.\n\nBy 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.\n\nIf you don't specify the `--outfile` option, then the bundled API will be written to stdout, which means you can pipe it to other commands.\n\nThe 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.\n\n```\nswagger-cli bundle [options] \u003cfile\u003e\n\nOptions:\n    -o, --outfile \u003cfile\u003e        The output file\n\n    -r, --dereference           Fully dereference all $ref pointers\n\n    -f, --format \u003cspaces\u003e       Formats the output using the given number of spaces\n                                (the default is 2 spaces)\n\n    -t, --type \u003cfiletype\u003e       Defines the output file type. The valid values are: json, yaml\n                                (the default is JSON)\n\n    -w, --wrap \u003ccolumn\u003e         Set the line length for YAML strings\n                                (the default is no wrapping)\n```\n\n\n\nContributing\n--------------------------\nI welcome any contributions, enhancements, and bug-fixes.  [Open an issue](https://github.com/APIDevTools/swagger-cli/issues) on GitHub and [submit a pull request](https://github.com/APIDevTools/swagger-cli/pulls).\n\n#### Building/Testing\nTo build/test the project locally on your computer:\n\n1. **Clone this repo**\u003cbr\u003e\n`git clone https://github.com/APIDevTools/swagger-cli.git`\n\n2. **Install dependencies**\u003cbr\u003e\n`npm install`\n\n3. **Run the tests**\u003cbr\u003e\n`npm test`\n\n\n\nLicense\n--------------------------\nSwagger CLI is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.\n\nThis package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/APIDevTools/swagger-cli) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.\n\n\n\nBig Thanks To\n--------------------------\nThanks to these awesome companies for their support of Open Source developers ❤\n\n[![Travis CI](https://jstools.dev/img/badges/travis-ci.svg)](https://travis-ci.com)\n[![SauceLabs](https://jstools.dev/img/badges/sauce-labs.svg)](https://saucelabs.com)\n[![Coveralls](https://jstools.dev/img/badges/coveralls.svg)](https://coveralls.io)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapidevtools%2Fswagger-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapidevtools%2Fswagger-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapidevtools%2Fswagger-cli/lists"}