unused-shared-component

Since 0.0.1 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error

This rule checks that every component of the document is reachable from its paths, webhooks, security requirements or tags.

Rule details

A component nothing refers to is dead weight that every reader, generator and reviewer still has to go through: a schema of a resource the API no longer has, a response that an operation stopped using. Generated clients get a type for it, documentation a section.

The rule starts from the parts of the document outside components (paths, webhooks, security requirements, tags, extensions, …) and follows references ($ref, discriminator mappings and security requirement names) transitively. Every component it cannot reach is reported as Unused shared component, including components used only by other unused components.

A document without operations (no path items and no webhooks) is taken to be a library of components for other documents and is not checked. Turn the rule off for a document that has operations and also publishes components for other documents to reference.

Examples

Good. The User schema is referenced by a parameter.

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/User"

Bad. Nothing refers to the User schema.

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer

Automatic fixes

--fix removes the components the rule reports. It keeps the components disabled with x-apigenie-lint-disable and what they refer to, and the local targets of references and discriminator mappings it could not resolve.

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.rules has the details.

commands:
  lint:
    rules:
      unused-shared-component: off
Was this helpful?