{"id":13578237,"url":"https://github.com/wework/speccy","last_synced_at":"2025-05-15T05:06:23.849Z","repository":{"id":39678744,"uuid":"119732137","full_name":"wework/speccy","owner":"wework","description":"Well Spectually 🤓 Enforce quality rules on your OpenAPI 3.0.x specifications.","archived":false,"fork":false,"pushed_at":"2022-12-30T17:22:48.000Z","size":4726,"stargazers_count":832,"open_issues_count":85,"forks_count":78,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-14T08:09:28.601Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://speccy.io","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/wework.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-31T19:21:02.000Z","updated_at":"2025-04-07T14:29:26.000Z","dependencies_parsed_at":"2023-01-31T12:16:24.227Z","dependency_job_id":null,"html_url":"https://github.com/wework/speccy","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wework%2Fspeccy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wework%2Fspeccy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wework%2Fspeccy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wework%2Fspeccy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wework","download_url":"https://codeload.github.com/wework/speccy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"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":[],"created_at":"2024-08-01T15:01:28.692Z","updated_at":"2025-05-15T05:06:23.773Z","avatar_url":"https://github.com/wework.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Linters","API","Visual Documentation Tools"],"sub_categories":["OpenAPI (Swagger)"],"readme":"# speccy\n\n[![CircleCI](https://circleci.com/gh/wework/speccy.svg?style=svg)](https://circleci.com/gh/wework/speccy)\n[![Coverage Status](https://coveralls.io/repos/github/wework/speccy/badge.svg)](https://coveralls.io/github/wework/speccy)\n[![Known Vulnerabilities](https://snyk.io/test/npm/speccy/badge.svg)](https://snyk.io/test/npm/speccy)\n\nMake sure your OpenAPI 3.0 specifications are more than just valid, make sure they're useful!\n\nTaking off from where [Mike Ralphson] started with linting in [swagger2openapi], Speccy aims to become the [rubocop] or [eslint] of OpenAPI.\n\n## Requirements\n\n- **NodeJS:** v8 - v10\n\n## OpenAPI Specification\n\nCurrently tracking [v3.0.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)\n\nIf you want to run speccy on OpenAPI (f.k.a Swagger) v2.0 specs, run it through [swagger2openapi] first and speccy can give advice on the output.\n\n## Setup\n\nYou can install this node module via NPM or Yarn.\n\n```sh\n$ npm install speccy -g\n# or\n$ yarn global add speccy\n```\n\nAlternatively, you can use it with Docker (see \"Using Docker\" below.)\n\n## Usage\n\n```\nUsage: speccy \u003ccommand\u003e\n\n\nOptions:\n\n-V, --version              output the version number\n-c, --config [configFile]  config file (containing JSON/YAML). See README for potential values.\n-h, --help                 output usage information\n\n\nCommands:\n\nlint [options] \u003cfile-or-url\u003e     ensure specs are not just valid OpenAPI, but lint against specified rules\nresolve [options] \u003cfile-or-url\u003e  pull in external $ref files to create one mega-file\nserve [options] \u003cfile-or-url\u003e    view specifications in beautiful human readable documentation\n```\n\n### Lint Command\n\nThe goal here is to sniff your files for potentially bad things. \"Bad\" is subjective, but you'll see validation errors, along with special rules for making your APIs better..\n\n```\nUsage: lint [options] \u003cfile-or-url\u003e\n\nensure specs are not just valid OpenAPI, but lint against specified rules\n\nOptions:\n\n  -q, --quiet             reduce verbosity\n  -r, --rules [ruleFile]  provide multiple rules files\n  -s, --skip [ruleName]   provide multiple rules to skip\n  -j, --json-schema       treat $ref like JSON Schema and convert to OpenAPI Schema Objects\n  -v, --verbose           set verbosity (use multiple times to increase level)\n  -h, --help              output usage information\n```\n\nYou'll see output such as:\n\n```\n#/info  R: info-contact  D: info object should contain contact object\n\nexpected Object {\n  version: '5.0',\n  title: 'Foo API'\n} to have property contact\n```\n\nThere are going to be different things people are interested in, so the [default rules][rules-default] suggest things we think everyone should do; adding descriptions to parameters and operations, and having some sort of contact info.\n\nThere are [strict rules][rules-strict] which demand more contact details, \"real\" domains, a license, and requires tags have a description!\n\n### Resolve Command\n\nResolving `$ref` is the art of taking multiple files and squashing them all down into one big OpenAPI file. By default it will output to stdout, but you can pass `-o` with a file name to write the file locally.\n\n```\nUsage: resolve [options] \u003cfile-or-url\u003e\n\npull in external $ref files to create one mega-file\n\nOptions:\n\n  -o, --output \u003cfile\u003e  file to output to\n  -q, --quiet          reduce verbosity\n  -j, --json-schema    treat $ref like JSON Schema and convert to OpenAPI Schema Objects\n  -v, --verbose        set verbosity (use multiple times to increase level)\n  -h, --help           output usage information\n```\n\nStarting with the fantastic resolver logic form swagger2openapi, speccy has one of the most robust\nresolvers out there. It avoid cyclical dependencies (when A has a property that `$ref`s A, which in turn destroys your CPU), and all sorts of other things.\n\nThanks to the `--json-schema` switch, you can have an OpenAPI file which `$ref`s JSON Schema files (not just OpenAPI-flavoured JSON Schema), then resolve them all into one real OpenAPI file, thanks to [wework/json-schema-to-openapi-schema].\n\n### Serve Command\n\nUsing [ReDoc], speccy can offer a preview of your specifications, in human-readable format.\nIn the future we'll have speccy outlining improvements right in here, but one thing at a time.\n\n```\nUsage: serve [options] \u003cfile-or-url\u003e\n\nview specifications in beautiful human readable documentation\n\nOptions:\n\n  -p, --port [value]  port on which the server will listen (default: 5000)\n  -q, --quiet         reduce verbosity\n  -j, --json-schema   treat $ref like JSON Schema and convert to OpenAPI Schema Objects\n  -v, --verbose       set verbosity (use multiple times to increase level)\n  -h, --help          output usage information\n```\n\n### Config File\n\nTo avoid needing to send command line options and switches every time, a config file can be used. Create\na `speccy.yaml` in the root of your project.\n\nExample:\n```yaml\n# Convert JSON Schema-proper to OpenAPI-flavoured Schema Objects\njsonSchema: true\n# Keep the noise down\nquiet: true\n# Output a lot of information about what is happening (wont work if you have quiet on)\n# Default stdout = 1\nverbose: 2\n# Rules specific to the lint command\nlint:\n  # rules files to load\n  rules:\n  - strict\n  - ./some/local/rules.yaml\n  - https://example.org/my-rules.yaml\n  # rules to skip\n  skip:\n  - info-contact\n# Rules specific to the resolve command\nresolve:\n  output: foo.yaml\n# Rules specific to the serve command\nserve:\n  port: 8001\n```\n\n### Calling Speccy from Code\n\nNot just a command line tool, speccy can be used to normalize machine-readable specifications.\n\nThe loader object will return a promise that resolves to an object containing\nthe specification.  For example:\n\n``` javascript\nconst loader = require('speccy/lib/loader');\n\nconst options = {\n  resolve: true,   // Resolve external references\n  jsonSchema: true // Treat $ref like JSON Schema and convert to OpenAPI Schema Objects\n};\n\nloader\n  .loadSpec('path/to/my/spec', options)            // Load the spec...\n  .then(spec =\u003e console.log(JSON.stringify(spec))); // ...and print it out.\n```\n\nIf `options.resolve` is truthy, speccy will resolve _external_ references.\n\n### Using Docker\n\nTo use Speccy without installing any node/npm specific dependencies, you can run it via docker:\n\n``` shell\ndocker run wework/speccy lint https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml\n```\n\nYou can work with local files by mounting your spec and any config files to the `/project` directory when you run the container:\n\n```\ndocker run \\\n  -v openapi.yaml:/project/openapi.yaml \\\n  wework/speccy lint openapi.yaml\n```\n\nAlso, if you want to use a specific version, you can reference tags, so `docker run wework/speccy` could be `docker run wework/speccy:0`, \n`docker run wework/speccy:0.8` or `docker run wework/speccy:0.8.7`. These versions follow semantic versioning.\n\n### Using with lint-staged\n\nTo lint your specifications before committing them you can use [lint-staged](https://github.com/okonet/lint-staged) to run speccy before each commit. Just install lint-staged and husky as `devDependencies` and add the following to your `package.json`:\n\n```\n\"husky\": {\n  \"hooks\": {\n    \"pre-commit\": \"lint-staged\"\n  }\n},\n\"lint-staged\": {\n  \"*.{yml, yaml}\": [\"speccy lint openapi.yml\", \"git add\"]\n}\n```\nYou can of course adjust the file filter and the speccy command to fit your setup.\n\n## Tests\n\nTo run the test-suite:\n\n```shell\nnpm test\n```\n\n## Contributing\n\nContributions are always welcome, no matter how large or small. Before contributing, please read the [code of conduct](CODE_OF_CONDUCT.md).\n\n## Credits\n\n- [Mike Ralphson] for providing the initial linter/validator from [swagger2openapi]\n- [Roman Gotsiy] for the excellent [ReDoc]\n- [Kenta Mori] for providing the serve logic from [redocup]\n- [All Contributors][link-contributors]\n\n## License\n\n[MIT](LICENSE) except the `openapi-3.0.json` schema, which is taken from the [OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/49e784d7b7800da8732103aa3ac56bc7ccde5cfb/schemas/v3.0/schema.yaml) and the alternative `gnostic-3.0.json` schema, which is originally from [Google Gnostic](https://github.com/googleapis/gnostic/blob/master/OpenAPIv3/openapi-3.0.json). Both of these are licensed under the [Apache-2](http://www.apache.org/licenses/LICENSE-2.0) license.\n\n[Kenta Mori]: https://github.com/zoncoen/\n[Mike Ralphson]: https://twitter.com/PermittedSoc/\n[ReDoc]: https://github.com/Rebilly/ReDoc\n[Roman Gotsiy]: https://github.com/RomanGotsiy\n[eslint]: https://eslint.org/\n[link-contributors]: https://github.com/wework/speccy/graphs/contributors\n[redocup]: https://github.com/zoncoen/redocup/\n[rubocop]: https://github.com/bbatsov/rubocop\n[rules-default]: http://speccy.io/rules/1-rulesets#set-default\n[rules-strict]: http://speccy.io/rules/1-rulesets#set-strict\n[swagger2openapi]: https://github.com/Mermade/swagger2openapi/\n[wework/json-schema-to-openapi-schema]: https://github.com/wework/json-schema-to-openapi-schema\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwework%2Fspeccy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwework%2Fspeccy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwework%2Fspeccy/lists"}