unused-shared-component
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether every shared object of a Swagger 2.0 document is actually used.
Rule details
Shared objects that are never used make the document longer and harder to maintain, and suggest that something is missing (for example, a response that was defined but never attached to an operation).
The unused-shared-component rule checks every entry of the root
definitions, parameters, responses and securityDefinitions maps, and
reports Unused shared component for every entry that is not used:
- An entry of
definitions,parametersorresponsesis used when a local$refof the form#/<section>/<name>(possibly pointing deeper into the entry, e.g.#/definitions/Pet/properties/name) appears anywhere outside these three sections, or inside another used entry. References are followed transitively, so a definition used only by an unused response is unused as well. References nested in untyped values, such as vendor extensions, count too. - An entry of
securityDefinitionsis used when its name appears in the rootsecurityrequirements or in thesecurityrequirements of an operation.
An entry that has this rule disabled (see below) is always considered used, and so is everything it references.
The OpenAPI linter has a rule of the same name, unused-shared-component, for OpenAPI 3.x documents.
Turn the rule off for documents that serve as libraries of shared objects, referenced from other documents.
Examples
Good. Every shared object is used, directly or through another one.
swagger: '2.0'
info:
title: Pets
version: 1.0.0
securityDefinitions:
apiKey:
type: apiKey
name: X-API-Key
in: header
security:
- apiKey: []
paths:
/pets:
get:
parameters:
- $ref: '#/parameters/limit'
responses:
'200':
$ref: '#/responses/Pets'
parameters:
limit:
name: limit
in: query
type: integer
responses:
Pets:
description: Pets
schema:
type: array
items:
$ref: '#/definitions/Pet'
definitions:
Pet:
type: object
properties:
owner:
$ref: '#/definitions/Owner'
Owner:
type: object
Bad. The basic security scheme, the offset parameter and the Shelter
definition are not used.
swagger: '2.0'
info:
title: Pets
version: 1.0.0
securityDefinitions:
apiKey:
type: apiKey
name: X-API-Key
in: header
basic:
type: basic
security:
- apiKey: []
paths:
/pets:
get:
parameters:
- $ref: '#/parameters/limit'
responses:
'200':
description: Pets
parameters:
limit:
name: limit
in: query
type: integer
offset:
name: offset
in: query
type: integer
definitions:
Shelter:
type: object
To keep a shared object that is meant to be referenced from other documents, disable the rule on it:
swagger: '2.0'
info:
title: Pets
version: 1.0.0
paths: {}
definitions:
Library:
x-lint-disable: [unused-shared-component]
type: object
properties:
item:
$ref: '#/definitions/Item'
Item:
type: object
Automatic fixes
--fix removes all unused entries. When every
entry of a section is unused, the whole section is removed, so that no empty
map is left behind.
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.
commands:
lint:
swagger:
rules:
unused-shared-component: off