eslint-plugin-swagger

{•••} An extensible linter with semantic validations for Swagger specifications.

1. Table of contents

• 1. Table of contents
• 2. Installation
• 3. Usage
• 4. Supported rules
• 5. Rules in backlog
• 6. Contributions
• 7. License

2. Installation

You'll first need to install ESLint:

$ npm i eslint --save-dev

Next, install eslint-plugin-swagger:

$ npm install eslint-plugin-swagger --save-dev

Note: If you installed ESLint globally (using the -g flag) then you must also install eslint-plugin-swagger globally.

3. Usage

ℹ️ Swagger file extensions

eslint-plugin-swagger evaluates Swagger files that have a .json, .yaml, or .yml file extension.

Add swagger to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{
    "plugins": [
        "swagger"
    ]
}

Then configure the rules you want to use under the rules section.

{
    "rules": {
        "swagger/rule-name": 2
    }
}

Finally, run ESLint against your Swagger documents.

$ eslint path/to/swagger/docs/** --fix

4. Supported rules

options legend

• ✔️ The rule's log threshold can be extended or disabled
• 🔧 Supports the --fix command line option

options	Rule	Description	Status
	no-dup-paths	Each API path should be unique.	Completed
	no-path-verbs	Prohibit verbs in api paths	Completed
🔧	require-plural-paths	Require plural nouns in API paths	Completed

5. Rules in backlog

The product backlog has lots of lonely rules looking for love from nice contributors like you. 😘 If you're interested, please:

1. Set up an eslint-plugin development environment.
2. Read the contribution guidelines.
3. Select the rule you want to work on to create a pull request.
4. Follow the Contributor Covenant Code of Conduct.
5. Achieve fame and glory!

ℹ️ Select a rule's name to open a new issue.

options	Rule	Description	Status
	no-circular-refs	A definition/model's ancestor cannot be a descendant of said model. (Circular Reference)	Available
	no-definitions-without-refs	Each reference-able definition must have references.	Available
	no-dup-ancestors	A definition/model cannot declare a property that is already defined by one of its ancestors.	Available
	no-dup-auth-definition-refs	Each authorization/security scope in an authorization/security definition should be unique.	Available
	no-dup-auth-scope-refs	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
	no-dup-name-type-pair	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
	no-dup-op-methods	Each operation in an API should have a unique method property.	Available
	require-uniform-params	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
	no-dup-resource-paths	Each resourcePath should be unique for each API Declaration in the API.	Available
	no-dup-response-message-code	Each code in an operation's responseMessages should be unique.	Available
	no-empty-requireds	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
	no-form-and-body	An operation cannot have a form or formData parameter if it has a body parameter	Available
	no-id-model-mismatch	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
	no-multiple-inheritance	Models are not allowed to descend from multiple models. (Multiple Inheritance)	Available
	no-undefined-ref-definition	Each reference must point to an existing definition.	Available
	operation-body	Each operation should have only one parameter of type body	Available
	path-definition	The Resource Listing has an API whose path is not defined in any of the API Declarations.	Available
	require-array-items	The items property is required for all schemas/definitions of type array. (See swagger-api/swagger-spec/issues/174)	Available
	require-default-value	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)	Available
	require-path-definition	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

6. Contributions

👪 We warmly welcome contributors. Check out the guidelines for Contributing to eslint-plugin-swagger and our Contributor Covenant Code of Conduct.

Contributions are stories with a beginning, a middle, and an end, all told through issues and pull requests.

• Peruse open issues or
• View rules in the backlog
• Open a new pull request (PR)

7. License

Apache 2.0 ©️ Greg Swindle.

---