audience-defined
Since 0.9.0 · In the rulesets: Strict at error, All at error
This rule checks whether the intended audience of an API is declared in the
#/info/x-audience extension of an AsyncAPI document.
Rule details
Knowing who an API is built for helps to decide how strict its review should be, how carefully breaking changes must be handled, and where the API can be published. AsyncAPI does not provide a field for this information.
The audience-defined rule fills this gap. It requires the x-audience
extension to be present in the info object, and its value to be one of the
following strings:
internal-team- the API is used only by the team that owns it,internal-company- the API is used by other teams in the same company,partner- the API is shared with selected partners,public- the API is publicly available.
The rule reports API audience (x-audience) is missing when the extension
is absent, and API audience (x-audience) has invalid value (...) when its
value is not one of the strings listed above (including values that are not
strings at all).
Turn the rule off if your organization does not classify its APIs by their audience.
Examples
Good. The audience of the API is clearly stated.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
x-audience: internal-company
Bad. The audience is not declared.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
Bad. The audience has a value that is not recognized.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
x-audience: everyone
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:
audience-defined: off