Release Notes v1.22.0

Adds audience filtering to the openapi3 package, plus a matching oas3filter CLI. Mark operations x-audience: internal, partner or public (or x-internal: true) in one spec, and write a spec for each audience with only the operations it may see and only the components they use. RAML 0.8 conversion also gains tags and a spec builder. This is an additive, backward-compatible release.

Highlights

  • Audience filtering (openapi3.AudienceFilter): keep the operations an audience may see, with internal as the default for unmarked operations so nothing is published by mistake.
  • Filtered export with pruning (SpecMore.ExportByFilter): copy kept operations with every component they reach, and nothing else, checked for unresolved references.
  • oas3filter CLI: write a public or partner spec from the command line, the same every time for the same input.

New Features

Audiences

keep, err := openapi3.AudienceFilter(openapi3.AudiencePublic, openapi3.AudienceInternal)
if err != nil {
    panic(err)
}
sm := openapi3.SpecMore{Spec: spec}
public, err := sm.ExportByFilter(keep, &openapi3.FilterOptions{
    RemoveExtensions: []string{openapi3.XAudience, openapi3.XInternal},
})
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. An operation's audience comes from its own x-audience or x-internal, then its path item's, then the default. x-audience may be a string or a list, whose widest audience applies. x-internal: true wins over x-audience, so conflicting marks never widen who sees something.

API surface:

Symbol Purpose
Audience, AudienceInternal, AudiencePartner, AudiencePublic Audiences, narrowest to widest
ParseAudience(s string) (Audience, error) Read an audience name
Audience.VisibleTo(reader Audience) bool Whether something for one audience may be shown to another
ExtensionAudience(ext map[string]any) (Audience, bool, error) Read x-audience or x-internal
AudienceFilter(reader, def Audience) (OperationFilterFunc, error) A filter for one audience
XAudience, XInternal The extension names

Filtered export

SpecMore.ExportByFilter(keep OperationFilterFunc, opts *FilterOptions) (*Spec, error) writes a new spec with the operations keep accepts, in paths and webhooks. It follows references through allOf, oneOf, anyOf, items, additionalProperties and every component kind, keeps only the security schemes and tags in use, leaves the source unchanged, and fails on a reference that points nowhere. It works with any filter, not only audiences.

oas3filter CLI

oas3filter -i openapi.json -o openapi-public.json -a public

See Filtering specs by audience.

RAML 0.8 conversion

raml08openapi3.ReadFileOperations now tags each operation with its RAML resource's displayName, so a converted spec keeps the resource grouping. raml08openapi3.NewSpec turns those operations into an OpenAPI 3 spec:

oms, err := raml08openapi3.ReadFileOperations("api.raml08.json")
if err != nil {
    panic(err)
}
spec, err := raml08openapi3.NewSpec(*oms, "My API", "v1")

NewSpec returns an error for an unset operation or for two operations with one path and method.

Fixes

  • raml08openapi3.ReadFileOperations panicked on a method whose value is not an object. It now returns ErrRAMLMethodNotObject, and reads a null method, as a bare get: produces, as one with no properties.

Dependencies

  • openapi3 uses the standard library slices package. golang.org/x/exp is now an indirect dependency.