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, parameters or responses is used when a local $ref of 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 securityDefinitions is used when its name appears in the root security requirements or in the security requirements 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

Related rules

Further reading

Was this helpful?