go-asyncapi is a tool for working with AsyncAPI documents.
AsyncAPI is a specification for defining APIs for event-driven architectures. The AsyncAPI document describes the messages, channels, servers, and other entities that the systems in event-driven architecture use to communicate with each other.
Core features #
| Feature | Command | |
|---|---|---|
 | Generating the Go boilerplate code for any protocol | go-asyncapi code |
 | Building the zero-code CLI client executable | go-asyncapi client |
 | Generating the server definitions | go-asyncapi infra |
 | Drawing the SVG diagrams | go-asyncapi diagram |
 | Serving or generating the web docs UI | go-asyncapi ui |
See the Features page for more details.
Supported protocols #
go-asyncapi is able to generate the abstract code for any protocol, but for these protocols it also adds the supporting code:
| Protocol | Implementation library | |
|---|---|---|
 | AMQP | github.com/rabbitmq/amqp091-go |
 | HTTP | net/http |
 | IP RAW Sockets | net |
 | Apache Kafka | github.com/twmb/franz-go |
 | MQTT v3 | github.com/eclipse/paho.mqtt.golang |
| MQTT v5 | github.com/eclipse/paho.golang |
 | NATS | github.com/nats-io/nats.go |
 | Redis | github.com/redis/go-redis |
 | TCP | net |
| UDP | net |
 | WebSocket | github.com/gobwas/ws |
Installation #
go install github.com/bdragon300/go-asyncapi/cmd/go-asyncapi@latest
Usage #
Demo applications:
These couple of high-level examples show how to use the generated code for sending and receiving messages. The low-level functions are also available, which gives more control over the process.
Publishing:
ctx := context.Background()
// Connect to broker for sending messages
myServer, err := servers.ConnectMyServerProducer(ctx, servers.MyServerURL())
if err != nil {
log.Fatalf("connect to the myServer: %v", err)
}
defer myServer.Close()
// Open an channel for sending messages
myChannel, err := myServer.OpenMyChannelKafka(ctx)
if err != nil {
log.Fatalf("open myChannel: %v", err)
}
defer myChannel.Close()
// Craft a message
msg := messages.MyMessage{
Payload: schemas.MyMessagePayload{
Field1: "value1",
Field2: 42,
},
Headers: schemas.MyMessageHeaders{
Header1: "header1",
},
}
// Send a message
if err := myChannel.PublishMyMessage(ctx, msg); err != nil {
log.Fatalf("send message: %v", err)
}
Subscribing:
ctx := context.Background()
// Connect to broker for receiving messages
myServer, err := servers.ConnectMyServerConsumer(ctx, servers.MyServerURL())
if err != nil {
log.Fatalf("connect to the myServer: %v", err)
}
defer myServer.Close()
// Open an channel for sending messages
myChannel, err := myServer.OpenMyChannelKafka(ctx)
if err != nil {
log.Fatalf("open myChannel: %v", err)
}
defer myChannel.Close()
// Subscribe to messages
err := myChannel.SubscribeMyMessage(ctx, func(msg messages.MyMessage) {
log.Printf("received message: %+v", msg)
})
if err != nil {
log.Fatalf("subscribe: %v", err)
}
Project status #
The project is in active development and is considered unstable. API may change.
Description #
Goals #
The goal of the project is to help the developers, DevOps, QA, and other engineers with making the software in event-driven architectures based on the AsyncAPI.
Another goal is to provide a way to prototype and test everything described in AsyncAPI document without coding.
The third goal is full support of the AsyncAPI specification and to make it available to use with modern protocols.
Features overview #
go-asyncapi supports most of the AsyncAPI features, such as messages, channels, servers, bindings, correlation ids, etc.
The generated Go boilerplate code has minimal dependencies on external libraries and contains the basic logic sufficient to
send and receive messages. You also can plug in the protocol implementations built-in in go-asyncapi, they are based on
popular libraries for that protocol. Also, it is possible to import the third-party code in the code being generated.
It is possible to build the no-code client application solely based on the AsyncAPI document, which is useful for testing purposes or for quick prototyping.
The go-asyncapi is able to generate the infrastructure setup files, such as Docker Compose files, which are useful
for setting up the development environment quickly or as the starting point for the infrastructure-as-code deploy configurations.
Another major feature is drawing the diagrams showing the relationships between things described in one or more AsyncAPI documents. This helps to visualize the architecture.
Web UI feature generates the AsyncAPI web docs. Using the AsyncAPI React Component,
go-asyncapi is able to generate a static HTML docs page or even serve it just in one command.
FAQ #
Why do I need another codegen tool? We already have the official generator #
Well, go-asyncapi provides more features, and it’s written in Go.
The official generator is quite specific for many use cases. At the moment, it produces the Go code bound with the Watermill framework, but not everyone uses the Watermill in their projects. Furthermore, a project may have a fixed set of dependencies, for example, due to the security policies in the company.
Also, the official generator supports only the AMQP protocol.
Instead, go-asyncapi:
- produces the framework-agnostic code for any protocol and additional supporting code for built-in protocols.
- besides the codegen feature, it can build client application, draw diagrams, generate server definitions, produce web docs.
- supports some specific AsyncAPI entities, such as protocol bindings, correlation ids, server variables, etc.
- has built-in clients for supported protocols, that are based on popular libraries.
- written in Go, so no need to have node.js or Docker or similar tools to run the generator.
Another reason is that I don’t know JavaScript well. And I’m not sure that if we want to support all AsyncAPI features, the existing templates would not be rewritten from the ground.
How to contribute? #
Just open an issue or a pull request. Branches master is the current release, dev is for development (next release).