Linter rulesSwagger 2.0audience-defined

audience-defined

Since 0.9.0

This rule checks whether the intended audience of an API is declared in the x-audience extension of the info object of a Swagger 2.0 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. Swagger 2.0 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. For values that are not strings at all the parentheses are empty.

Configuration

None.

Examples

Good. The audience of the API is clearly stated.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  x-audience: internal-company
paths: {}

Bad. The audience is not declared.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths: {}

Bad. The audience has a value that is not recognized.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  x-audience: everyone
paths: {}

When Not to Use It

You may disable this rule if your organization does not classify its APIs by their audience.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x and AsyncAPI documents are linted by the OpenAPI and AsyncAPI linters, which have their own audience-defined rules.

Related rules

Further reading