Visualizing AsyncAPI documents #

go-asyncapi can generate diagrams from AsyncAPI documents using D2 – a modern diagram scripting language. The resulting diagrams visualize the structure of the AsyncAPI document, including servers, channels, operations, messages and their relationships.

The diagram is generated internally as D2 script. By default, it’s additionally converted to SVG format, which allows to embed it in web pages, documentation, or share as a standalone file.

The result can also be customized in d2 script templates. See templating guide for more details.

Usage #

To generate a diagram, use the diagram subcommand:

$ go-asyncapi diagram my-app.yaml

Default result (SVG) will look like this:

By default, the command generates a file with the same name as the input file, but with .svg extension. You can change the output file name with the --output option. To generate the diagram in D2 format, use the --format d2.

Customization #

The diagram generation process has several built-in customization options.

The default draws operations as “endpoints” and both channels and servers as central nodes. Arrows between operations and channels indicate the message name and its flow direction.

All command-line options mentioned below are also can be set in configuration file, see configuration reference

Channel-centric and server-centric views #

The option --channels-centric makes channels as central nodes, servers are omitted, like shown below:

Another option --servers-centric leaves only servers, hiding channels:

Document borders #

By default, the diagram does not show which entities belong to which files. To enable this, use the --document-borders option.

D2 engine options #

Themes #

--d2-theme-id option selects a light color theme, while --d2-dark-theme-id generates the diagram using dark theme. If both options are set, the resulting SVG will be dual-theme where the theme switches automatically based on user’s system preferences (more info).

List of available themes can be found in the D2 documentation.

Other options #

D2 engine supports various options to customize the appearance of the diagram. See --help output or configuration reference for the full list.

For example, the --d2-sketch option makes the diagram look hand-drawn:

D2 engine sometimes may produce diagrams that looks ugly or that are hard to read due to overlapping nodes or edges. To get better results, you may try to play with various --d2-* CLI args (or appropriate config options), starting with --d2-engine and --d2-direction.

More customization #

You can create your own D2 templates to customize the diagram output. See templating guide for more details.