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. oas3filterCLI: 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.ReadFileOperationspanicked on a method whose value is not an object. It now returnsErrRAMLMethodNotObject, and reads a null method, as a bareget:produces, as one with no properties.
Dependencies¶
openapi3uses the standard libraryslicespackage.golang.org/x/expis now an indirect dependency.