audience-defined
Since 0.0.1 · In the rulesets: Strict at error, All at error
This rule checks that info has an x-audience field, and that its value is one of
internal-team, internal-company, partner and public.
Rule details
Who an API is for decides how much design review, documentation and lifecycle care it gets: an
API shared with partners or published to everyone is held to a higher standard than one used by
a single team. The audience has no place in the OpenAPI specification, so the rule looks for the
x-audience extension of the info object.
The rule reports API audience (x-audience) is missing when the field is absent, and
API audience (x-audience) has invalid value (...) when it is not one of the four values:
internal-team: used by the team that owns it.internal-company: used across the company.partner: used by selected external clients.public: available to everyone.
Examples
Good. The API says it is public.
openapi: 3.0.3
info:
title: Orders
version: 1.2.3
x-audience: public
paths: {}
Bad. The value is not one of the four.
openapi: 3.0.3
info:
title: Orders
version: 1.2.3
x-audience: external
paths: {}
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:
audience-defined: off