Filtering Specs by Audience

One spec can describe an API for several audiences: what everyone may call, what selected partners may call, and what only the API's own team uses. Spectrum writes the spec for one audience from it, keeping only the operations that audience may see and only the components, security schemes and tags those operations use. (Added in v1.22.0.)

Filtering removes operations from the file itself. Marking them hidden for a documentation tool is not enough on its own, since anyone can download the spec the tool reads.

Marking operations

Mark an operation, or a whole path, with x-audience:

paths:
  /v1/orders:
    get:
      x-audience: public
  /v1/orders/bulk-sync:
    post:
      x-audience: partner
  /v1/admin/reconcile:
    post:
      x-audience: internal
Audience Who sees it
internal The API's own team
partner Selected customers, and the API's own team
public Everyone

Each audience includes the narrower ones, so a public operation is in the partner and internal specs too. x-audience may also be a list, such as [partner, public], in which case the widest audience listed applies.

x-internal: true, as Redocly, Scalar and Stoplight read it, marks an operation as internal. When an operation has both marks, x-internal: true wins, so conflicting marks never widen who sees something.

An operation's own mark comes first, then its path item's, then a default. Use internal as the default so an operation nobody marked is never published by mistake. For a spec that marks only what is internal with x-internal, use public as the default.

Exporting

keep, err := openapi3.AudienceFilter(openapi3.AudiencePublic, openapi3.AudienceInternal)
if err != nil {
    log.Fatal(err)
}

sm := openapi3.SpecMore{Spec: spec}
public, err := sm.ExportByFilter(keep, &openapi3.FilterOptions{
    // Drop the marks once they have done their job.
    RemoveExtensions: []string{openapi3.XAudience, openapi3.XInternal},
})
if err != nil {
    log.Fatal(err)
}

ExportByFilter:

  • keeps the operations the filter accepts, in paths and webhooks, and drops path items left with none
  • copies every component the kept operations reach, following references through allOf, oneOf, anyOf, items, additionalProperties, shared responses, request bodies, parameters, headers, examples, links and callbacks
  • keeps only the security schemes the document and the kept operations require, and only the tags they use, in the source's order
  • leaves the source spec unchanged
  • reloads the result and fails on any reference that points nowhere

The output is the same every time for the same input, so it can be checked in and diffed.

ExportByFilter takes any OperationFilterFunc, so the same pruning works for filters by tag, path prefix or another extension.

From the command line

oas3filter -i openapi.json -o openapi-public.json -a public
oas3filter -i openapi.json -o openapi-partner.yaml -a partner
Flag Meaning
-i, --input Input spec, JSON or YAML
-o, --output Output spec; YAML when it ends in .yaml or .yml, else JSON
-a, --audience internal, partner or public
--default Audience of unmarked operations. Default internal
--keep-extensions Keep x-audience and x-internal in the output