unused-shared-component

Since 0.0.1 · fixed by --fix

This rule checks whether all components defined in an OpenAPI schema are used.

Rule Details

The unused-shared-component rule is designed to ensure that each shared component defined in an OpenAPI schema is used at least once. Unused components can lead to confusion and unnecessary bloat in the API’s structure.

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, including components used only by other unused components.

A document without operations (no path items and no webhooks) is treated as a library of components for other documents and is not checked.

Automatic Fixes

The automatic fix removes components proven unreachable from document roots. It retains disabled components and their dependencies, plus exact local targets named by source-only or unresolved local references and discriminator mappings. External references do not retain unrelated local components.

Configuration

None.

Examples

Good. The shared User schema is referenced by path item 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. The shared User schema is not used.

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

When Not to Use It

Disable the rule for documents that have operations but also publish components for other documents to reference.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.