Flattening the AsyncAPI documents #

TLDR; #

go-asyncapi doc flatten command resolves all $refs in a document and replaces them with the objects they refer to, producing a single self-contained document.

Arguments #

Command receives one argument, the path to the document to flatten. The path can be a local file or a URL, both YAML and JSON documents are supported.

By default, only $refs to local objects (inside the same document) are replaced. To also resolve $refs to other documents on the local filesystem, use --external-refs. To resolve $refs addressed by HTTP(s) URLs, use --remote-refs.

The AsyncAPI specification explicitly demands $ref to be used in certain places, e.g. channel field in “Operation Object”, etc. flatten respects this and leaves these $refs unresolved to keep the document valid.

See AsyncAPI specification.

The $ref locator options are described in the reference locator article.

Usage #

To flatten a document in-place:

go-asyncapi doc flatten my-app.yaml

To write the result to another file instead of modifying the original, use the -o (--output) option:

go-asyncapi doc flatten my-app.yaml -o flattened.yaml

To inline $refs pointing to other documents on the local filesystem, use --external-refs:

go-asyncapi doc flatten --external-refs my-app.yaml

To inline all $refs, including those addressed by URLs, add --remote-refs:

go-asyncapi doc flatten --external-refs --remote-refs my-app.yaml