audience-defined

This rule checks whether an OpenAPI schema defines its target audience.

Rule Details

Defining target audience for an API allows implementing different levels of quality of design, discoverability, completeness of the documentation, as well as extra steps in the API lifecycle.

The audience-defined rule is designed to ensure that the #/info/x-audience field is defined in an OpenAPI schema, and has one of allowed values. The allowed values for this attribute are:

• internal-team - internal API used by the team. This is most close in meaning to private API.
• internal-company - internal API accessible to the whole company.
• partner - API accessible to external clients.
• external - public API, accessible to everyone. This is a synonym to public API.

Configuration

None.

Examples

This rule should be used whenever an OpenAPI schema is being defined. For instance:

openapi: 3.0.3
info:
    title: Some public API
    version: 1.2.3
    x-audience: external
paths:
    ...

When Not to Use It

N/A.

Compatibility

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