{•••} An extensible linter with semantic validations for Swagger specifications.
- 1. Table of contents
- 2. Installation
- 3. Usage
- 4. Supported rules
- 5. Rules in backlog
- 6. Contributions
- 7. License
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.
eslint-plugin-swaggerevaluates Swagger files that have a.json,.yaml, or.ymlfile 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
- ✔️ The rule's log threshold can be extended or disabled
- 🔧 Supports the
--fixcommand 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 |
The product backlog has lots of lonely rules looking for love from nice contributors like you. 😘 If you're interested, please:
- Set up an
eslint-plugindevelopment environment. - Read the contribution guidelines.
- Select the rule you want to work on to create a pull request.
- Follow the Contributor Covenant Code of Conduct.
- Achieve fame and glory!
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 |
👪 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.
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent