Linter rulesSwagger 2.0unused-shared-component

unused-shared-component

Since 0.9.0 · fixed by --fix

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.

Configuration

None.

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

When invoked with --fix, this rule 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.

When Not to Use It

You may disable this rule for documents that serve as libraries of shared objects, referenced from other documents.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading