# unused-shared-component

Source: https://apigenie.pl/docs/linter/swagger/rules/unused-shared-component

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.

```yaml
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.

```yaml
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:

```yaml
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.