unused-shared-component
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether every shared component of an AsyncAPI document is actually used.
Rule details
Components that are never referenced make the document longer and harder to maintain, and suggest that something is missing (for example, a message that was defined but never attached to a channel).
The unused-shared-component rule checks every entry of every component
category: schemas, servers, channels, operations, messages,
securitySchemes, serverVariables, parameters, correlationIds,
replies, replyAddresses, externalDocs, tags, operationTraits,
messageTraits, serverBindings, channelBindings, operationBindings and
messageBindings. It reports Unused shared component for every component
that is not reachable from the rest of the document.
A component is reachable when a local $ref of the form
#/components/<category>/<name> (possibly pointing deeper into the
component, e.g. #/components/schemas/Pet/properties/name) appears anywhere
outside components, or inside another reachable component. References are
followed transitively, so a schema used only by an unused message is unused
as well. References nested in untyped values, such as bindings or payloads
in other schema formats, count too.
A component that has this rule disabled (see below) is always considered used, and so is everything it references.
Turn the rule off for documents that serve as libraries of shared components, referenced from other documents.
Examples
Good. The message is used by the channel, and the schema by the message.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
channels:
petAdopted:
address: pets.adopted
messages:
petAdopted:
$ref: "#/components/messages/PetAdopted"
components:
messages:
PetAdopted:
payload:
$ref: "#/components/schemas/Pet"
schemas:
Pet:
type: object
Bad. Nothing references the PetReturned message, so both the message
and the Shelter schema it uses are unused.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
channels:
petAdopted:
address: pets.adopted
messages:
petAdopted:
$ref: "#/components/messages/PetAdopted"
components:
messages:
PetAdopted:
payload:
$ref: "#/components/schemas/Pet"
PetReturned:
payload:
$ref: "#/components/schemas/Shelter"
schemas:
Pet:
type: object
Shelter:
type: object
To keep a component that is meant to be referenced from other documents, disable the rule on it:
components:
schemas:
Shelter:
type: object
x-lint-disable: [unused-shared-component]
Automatic fixes
--fix removes all unused components. When
every entry of a component category is unused, the whole category map is
removed, so that no empty map is left behind.
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.asyncapi has the details.
commands:
lint:
asyncapi:
rules:
unused-shared-component: off