{"id":14986592,"url":"https://github.com/gregswindle/eslint-plugin-swagger","last_synced_at":"2025-04-11T21:31:30.948Z","repository":{"id":90405051,"uuid":"91676244","full_name":"gregswindle/eslint-plugin-swagger","owner":"gregswindle","description":"An extensible linter with semantic validations for Swagger specifications.","archived":false,"fork":false,"pushed_at":"2019-01-27T09:45:59.000Z","size":214,"stargazers_count":10,"open_issues_count":25,"forks_count":2,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-03-25T18:53:59.697Z","etag":null,"topics":["api-linter","api-rest","eslint-plugin","linter","linter-plugin","open-api","open-api-specification","openapi","richardson-maturity-model","rmm","swagger","swagger-linter"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gregswindle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-18T09:41:32.000Z","updated_at":"2023-12-19T17:40:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"99ebe8a8-61cd-49ab-befd-d474c6e4b2e0","html_url":"https://github.com/gregswindle/eslint-plugin-swagger","commit_stats":{"total_commits":62,"total_committers":2,"mean_commits":31.0,"dds":"0.048387096774193505","last_synced_commit":"0615d8afb6ec459e8b8ba583abda30b467647edd"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregswindle%2Feslint-plugin-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregswindle%2Feslint-plugin-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregswindle%2Feslint-plugin-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregswindle%2Feslint-plugin-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gregswindle","download_url":"https://codeload.github.com/gregswindle/eslint-plugin-swagger/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482959,"owners_count":21111408,"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":["api-linter","api-rest","eslint-plugin","linter","linter-plugin","open-api","open-api-specification","openapi","richardson-maturity-model","rmm","swagger","swagger-linter"],"created_at":"2024-09-24T14:13:11.652Z","updated_at":"2025-04-11T21:31:30.660Z","avatar_url":"https://github.com/gregswindle.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `eslint-plugin-swagger`\n\n\u003e {•••} An extensible linter with semantic validations for Swagger specifications.\n\n[![License][license-image]][license-url] [![Readme Score][readme-score-img]][readme-score-url] [![Inline docs][inch-ci-img]][inch-ci-url] [![Build Status][travis-ci-img]][travis-ci-url] [![Codacy Badge][codacy-img]][codacy-url] [![Coverage Status][coveralls-img]][coveralls-url]\u003cbr\u003e\n[![NSP Status][nsp-img]][nsp-url] [![bitHound Dependencies][bithound-dep-img]][bithound-dep-url] [![bitHound Dev Dependencies][bithound-dev-dep-img]][bithound-dev-dep-url]\n\n## 1. Table of contents\n\u003c!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 --\u003e\n\n- [1. Table of contents](#1-table-of-contents)\n- [2. Installation](#2-installation)\n- [3. Usage](#3-usage)\n- [4. Supported rules](#4-supported-rules)\n- [5. Rules in backlog](#5-rules-in-backlog)\n- [6. Contributions](#6-contributions)\n- [7. License](#7-license)\n\n\u003c!-- /TOC --\u003e\n\n## 2. Installation\n\nYou'll first need to install [`ESLint`](http://eslint.org):\n\n```bash\n\n$ npm i eslint --save-dev\n\n```\n\nNext, install `eslint-plugin-swagger`:\n\n```bash\n\n$ npm install eslint-plugin-swagger --save-dev\n\n```\n\n**Note:** If you installed `ESLint` globally (using the `-g` flag) then you must also install `eslint-plugin-swagger` globally.\n\n## 3. Usage\n\n\u003e #### :information_source: Swagger file extensions\n\u003e `eslint-plugin-swagger` evaluates Swagger files that have a `.json`, `.yaml`, or `.yml` file extension.\n\nAdd `swagger` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:\n\n```json\n\n{\n    \"plugins\": [\n        \"swagger\"\n    ]\n}\n\n```\n\n\nThen configure the rules you want to use under the rules section.\n\n```json\n\n{\n    \"rules\": {\n        \"swagger/rule-name\": 2\n    }\n}\n\n```\n\nFinally, run `ESLint` against your Swagger documents.\n\n```bash\n\n$ eslint path/to/swagger/docs/** --fix\n```\n\n## 4. Supported rules\n\n\u003e ###### `options` legend\n\u003e\n\u003e * :heavy_check_mark: The rule's log threshold can be extended or disabled\n\u003e * :wrench: Supports the `--fix` command line option\n\n| `options`        | Rule | Description| Status |\n|:----------------:|:-----|:-----------|:-------|\n|  | [`no-dup-paths`][no-dup-paths-url] | Each API `path` should be unique.  | Completed |\n|  | [`no-path-verbs`][no-path-verbs-url] | Prohibit verbs in api paths | Completed |\n| :wrench: | [`require-plural-paths`][rule-plural-paths-url] | Require plural nouns in API paths | Completed |\n\n## 5. Rules in backlog\n\nThe product backlog has lots of lonely `rules` looking for love from nice contributors like you. :kissing_heart: If you're interested, please:\n\n1. Set up an [`eslint-plugin` development environment][eslint-dev-env-url].\n2. Read the [contribution guidelines](./.github/CONTRIBUTING.md).\n3. Select the rule you want to work on to create a pull request.\n4. Follow the [Contributor Covenant Code of Conduct][code-of-conduct-url].\n5. Achieve fame and glory!\n\n\u003e #### :information_source: Select a `rule`'s name to open a new issue.\n\n| `options`        | Rule | Description| Status |\n|:----------------:|:-----|:-----------|:-------|\n|  | [`no-circular-refs`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-circular-refs%29%3A%20A%20definition/model%27s%20ancest...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | A definition/model's ancestor cannot be a descendant of said model. _(Circular Reference)_  | Available |\n|  | [`no-definitions-without-refs`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-definitions-without-refs%29%3A%20Each%20referenceable%20definiti...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each reference-able definition must have references.  | Available |\n|  | [`no-dup-ancestors`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-dup-ancestors%29%3A%20A%20definition/model%20cannot%20d...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | A definition/model cannot declare a property that is already defined by one of its ancestors.  | Available |\n|  | [`no-dup-auth-definition-refs`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-dup-auth-definition-refs%29%3A%20Each%20authorization/security...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each authorization/security scope in an authorization/security definition should be unique.  | Available |\n|  | [`no-dup-auth-scope-refs`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-dup-auth-scope-refs%29%3A%20Each%20authorization/security...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each authorization/security reference should contain only unique scopes. _(Example: For an `oauth2` authorization/security requirement, when listing the required scopes, each scope should only be listed once.)_  | Available |\n|  | [`no-dup-name-type-pair`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-dup-name-type-pair%29%3A%20Each%20operation%20parameter%20sh...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each operation parameter should have a unique `name` and type combination, where Swagger 1.2 uses the `paramType` property and in Swagger 2.0 uses the `in` property to indicate type.  | Available |\n|  | [`no-dup-op-methods`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-dup-op-methods%29%3A%20Each%20operation%20in%20an%20API%20sh...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each operation in an API should have a unique `method` property.  | Available |\n|  | [`require-uniform-params`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28require-uniform-params%29%3A%20Each%20defined%20operation%20path...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each defined operation path parameters must correspond to a named element in the API's path pattern. _(For example, you cannot have a path parameter named `id` for the following path `/pets/{petId}` but you must have a path parameter named `petId`.)_  | Available |\n|  | [`no-dup-resource-paths`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-dup-resource-paths%29%3A%20Each%20%60resourcePath%60%20should%20...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each `resourcePath` should be unique for each API Declaration in the API.  | Available |\n|  | [`no-dup-response-message-code`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-dup-response-message-code%29%3A%20Each%20%60code%60%20in%20an%20operation...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each `code` in an operation's `responseMessages` should be unique.  | Available |\n|  | [`no-empty-requireds`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-empty-requireds%29%3A%20Each%20definition/model%20prope...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each definition/model property listed in the `required` array must be defined in the `properties` of the model itself or one of its ancestors.  | Available |\n|  | [`no-form-and-body`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-form-and-body%29%3A%20An%20operation%20cannot%20have%20a%20...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | An operation cannot have a `form` or `formData` parameter if it has a `body` parameter  | Available |\n|  | [`no-id-model-mismatch`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-id-model-mismatch%29%3A%20Each%20model%27s%20%60id%60%20property%20...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each model's `id` property must match the corresponding key in the `models` section of the API Declaration. _(For example, a model with an id of `Person` should be found at the `Person` property in the API Declaration's `models` property and the `Person`'s `id` value must be `Person`.)_  | Available |\n|  | [`no-multiple-inheritance`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-multiple-inheritance%29%3A%20Models%20are%20not%20allowed%20to%20d...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Models are not allowed to descend from multiple models. _(Multiple Inheritance)_  | Available |\n|  | [`no-undefined-ref-definition`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28no-undefined-ref-definition%29%3A%20Each%20reference%20must%20point%20t...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each reference must point to an existing definition.  | Available |\n|  | [`operation-body`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28operation-body%29%3A%20Each%20operation%20should%20have%20...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Each operation should have only one parameter of type `body`  | Available |\n|  | [`path-definition`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28path-definition%29%3A%20The%20Resource%20Listing%20has%20an...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | The Resource Listing has an API whose `path` is not defined in any of the API Declarations.  | Available |\n|  | [`require-array-items`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28require-array-items%29%3A%20The%20%60items%60%20property%20is%20req...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | The `items` property is required for all schemas/definitions of type `array`. _(See [swagger-api/swagger-spec/issues/174](https://github.com/swagger-api/swagger-spec/issues/174))_  | Available |\n|  | [`require-default-value`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28require-default-value%29%3A%20Every%20place%20where%20a%20default...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | Every place where a default value can be provided, the default value must validate against the corresponding schema/definition. _(This is not handled by JSON Schema validators, at least not the one I am using, so we have to do this manually.  See [json-schema/JSON-Schema-Test-Suite/pull/67](https://github.com/json-schema/JSON-Schema-Test-Suite/pull/67))_  | Available |\n|  | [`require-path-definition`](https://github.com/gregswindle/eslint-plugin-swagger/issues/new?title=feat%28require-path-definition%29%3A%20For%20each%20API%20path%20parameter...\u0026labels[]=ESLint%3A%20Rule\u0026labels[]=Status%3A%20Available\u0026labels[]=Type%3A%20Feature\u0026labels[]=Type%3A%20Docs) | For each API path parameter, all operations for the API path require corresponding path parameter definitions or the corresponding path parameter needs to be in the path's parameters.  | Available |\n\n## 6. Contributions\n:family: We warmly welcome contributors. Check out the guidelines for [Contributing to `eslint-plugin-swagger`](./.github/CONTRIBUTING.md) and our [Contributor Covenant Code of Conduct][code-of-conduct-url].\n\nContributions are stories with a beginning, a middle, and an end, all told through issues and pull requests.\n * [Peruse open issues][issues-url] or\n * [View rules in the backlog][rules-backlog-wiki-url]\n * [Open a new pull request (PR)][pr-url]\n\n## 7. License\n\n[Apache 2.0][license-url] :copyright: [Greg Swindle][author-url].\n\n---\n\n[![Greenkeeper badge][greenkeeper-img]][greenkeeper-url] [![StackShare][stackshare-img]][stackshare-url]\n\n[author-url]: https://github.com/gregswindle\n[bithound-dep-img]: https://www.bithound.io/github/gregswindle/eslint-plugin-swagger/badges/dependencies.svg\n[bithound-dep-url]: https://www.bithound.io/github/gregswindle/eslint-plugin-swagger/develop/dependencies/npm\n[bithound-dev-dep-img]: https://www.bithound.io/github/gregswindle/eslint-plugin-swagger/badges/devDependencies.svg\n[bithound-dev-dep-url]: https://www.bithound.io/github/gregswindle/eslint-plugin-swagger/develop/dependencies/npm\n[codacy-img]: https://api.codacy.com/project/badge/Grade/554fe390431b455a87ba6acde3ff2989?style=flat-square\n[codacy-url]: https://www.codacy.com/app/greg_7/eslint-plugin-swagger?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=gregswindle/eslint-plugin-swagger\u0026amp;utm_campaign=Badge_Grade\n[code-of-conduct-url]: ./.github/CODE_OF_CONDUCT.md\n[coveralls-img]: https://coveralls.io/repos/github/gregswindle/eslint-plugin-swagger/badge.svg?branch=develop\n[coveralls-url]: https://coveralls.io/github/gregswindle/eslint-plugin-swagger?branch=develop\n[eslint-dev-env-url]: http://eslint.org/docs/developer-guide/development-environment\n[greenkeeper-img]: https://badges.greenkeeper.io/gregswindle/eslint-plugin-swagger.svg?style=flat-square\n[greenkeeper-url]: https://greenkeeper.io/\n[inch-ci-img]: http://inch-ci.org/github/gregswindle/eslint-plugin-swagger.svg?branch=develop\u0026style=flat-square\n[inch-ci-url]: http://inch-ci.org/github/gregswindle/eslint-plugin-swagger\n[issues-new-url]: https://github.com/gregswindle/eslint-plugin-swagger/issues/new\n[issues-url]: https://github.com/gregswindle/eslint-plugin-swagger/issues\n[license-image]: https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square\n[license-url]: ./LICENSE\n[no-dup-paths-url]: ./docs/rules/no-dup-paths.md\n[no-path-verbs-url]: ./docs/rules/no-path-verbs.md\n[nsp-img]: https://nodesecurity.io/orgs/gregswindle/projects/2761fa76-bf1a-4e31-a642-679dfe55e575/badge\n[nsp-url]: https://nodesecurity.io/orgs/gregswindle/projects/2761fa76-bf1a-4e31-a642-679dfe55e575\n[pr-url]: https://github.com/gregswindle/eslint-plugin-swagger/pulls\n[readme-score-img]: http://readme-score-api.herokuapp.com/score.svg?url=https://github.com/gregswindle/eslint-plugin-swagger\n[readme-score-url]: http://clayallsopp.github.io/readme-score?url=https://github.com/gregswindle/eslint-plugin-swagger\n[rule-plural-paths-url]: ./docs/rules/require-plural-paths.md\n[rules-backlog-wiki-url]: https://github.com/gregswindle/eslint-plugin-swagger/wiki/Rules-backlog\n[stackshare-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat\n[stackshare-url]: https://stackshare.io/gregswindle/eslint-plugin-swagger\n[travis-ci-img]: https://travis-ci.org/gregswindle/eslint-plugin-swagger.svg?branch=develop\u0026style=flat-square\n[travis-ci-url]:  https://travis-ci.org/gregswindle/eslint-plugin-swagger\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregswindle%2Feslint-plugin-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgregswindle%2Feslint-plugin-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregswindle%2Feslint-plugin-swagger/lists"}