unused-shared-component

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 works by iterating over all the dictionaries defined in the Components object of the schema and checking if any component is not referenced by other schema objects. If an unused component is found, the rule raises a warning.

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

Only if the whole schema is intended to be a library of reusable components.

Compatibility

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