Repository files navigation

go-asyncapi is a Go implementation of theAsyncAPI specification.

AsyncAPI is a specification for defining APIs for event-driven architectures. TheAsyncAPI document describes the messages, channels, servers, and other entities that the systems in event-drivenarchitecture use to communicate with each other.

Documentation

	Feature	Command
	Generating the Go boilerplate code	go-asyncapi code
	Building the CLI client without writing the code	go-asyncapi client
	Generating the Infrastructure-As-Code (IaC) definitions	go-asyncapi infra

Also,go-asyncapi contains the built-inprotocol implementations based on popular libraries, allows theresult customization using Go templates and more.

See theFeatures page for more details.

	Protocol	Library
	AMQP	github.com/rabbitmq/amqp091-go
	Apache Kafka	github.com/twmb/franz-go
	HTTP	net/http
	IP RAW Sockets	net
	MQTT	github.com/eclipse/paho.mqtt.golang
	Redis	github.com/redis/go-redis
	TCP	net
	UDP	net
	Websocket	github.com/gobwas/ws

The following couple of high-level examples show how to use the generated code for sending and receiving messages.

Publishing:

ctx:=context.Background()// Connect to broker for sending messagesmyServer,err:=servers.ConnectMyServerProducer(ctx,servers.MyServerURL())iferr!=nil {log.Fatalf("connect to the myServer: %v",err)}defermyServer.Close()// Open an operation for sending messagesmyOperation,err:=myServer.OpenMyPubOperationKafka(ctx)iferr!=nil {log.Fatalf("open myPubOperation: %v",err)}defermyOperation.Close()// Craft a messagemsg:= messages.MyMessage{Payload: schemas.MyMessagePayload{Field1:"value1",Field2:42,},Headers: schemas.MyMessageHeaders{Header1:"header1",},}// Send a messageiferr:=myOperation.PublishMyMessage(ctx,msg);err!=nil {log.Fatalf("send message: %v",err)}

Subscribing:

ctx:=context.Background()// Connect to broker for receiving messagesmyServer,err:=servers.ConnectMyServerConsumer(ctx,servers.MyServerURL())iferr!=nil {log.Fatalf("connect to the myServer: %v",err)}defermyServer.Close()// Open an operation for receiving messagesmyOperation,err:=myServer.OpenMySubOperationKafka(ctx)iferr!=nil {log.Fatalf("open mySubOperation: %v",err)}defermyOperation.Close()// Subscribe to messageserr:=myOperation.SubscribeMyMessage(ctx,func(msg messages.MyMessage) {log.Printf("received message: %+v",msg)})iferr!=nil {log.Fatalf("subscribe: %v",err)}

The low-level functions are also available, which gives more control over the process.

Also, here are some demo applications:

• Site authorization
• HTTP echo server

go install github.com/bdragon300/go-asyncapi/cmd/go-asyncapi@latest

The project is in active development. The main features are implemented, but there are still some missing features andbugs.

This version supports the latest AsyncAPI v3. It doesn't support the previous v2, because v3 introduced some breakingchanges, so making the tool that supports both v2 and v3 requires a lot of effort and time with no significant benefits.

go-asyncapi usesSemantic Versioning for versioning. For example,1.4.0.

Releasing apatch version contains only bug fixes and minor improvements. You won't need to regenerate the code afterupgrading the tool. E.g.1.4.0 → 1.4.1.

Releasing aminor version means that the generated code may be affected, but without breaking changes. You may need toregenerate the code. E.g.1.4.0 → 1.5.0.

Major version release typically introduces the breaking changes. You may need to regenerate the code, to fix yourprojects that uses it or to change the tool command line. E.g.1.4.0 → 2.0.0.

Note, that the project major version 0 (0.x.x) is considered unstable

The goal of the project is, on the one hand, to fully implement the AsyncAPI specification and, on the other hand, to helpthe developers, DevOps, QA, and other engineers with making the software in event-driven architectures based on theAsyncAPI specification.

Another goal is to provide a way to readily use and test the technologies described in the AsyncAPI document —everything works out of the box, but each component is optional and can be replaced or omitted.

In other words,batteries included, but removable.

go-asyncapi supports most of the AsyncAPI features, such as messages, channels, servers, bindings, correlation ids, etc.

The generatedGo boilerplate code has minimal dependencies on external libraries and contains the basic logic sufficient tosend and receive messages. You also can plug in the protocol implementations built-in ingo-asyncapi, they are based onpopular libraries for that protocol. Also, it is possible to import the third-party code in the code being generated.

It is possible to build theno-code client application solely based on the AsyncAPI document, which is useful fortesting purposes or for quick prototyping.

Thego-asyncapi is able to generate theinfrastructure setup files, such as Docker Compose files, which are usefulfor setting up the development environment quickly or as the starting point for the infrastructure-as-code deploy configurations.

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 theWatermill framework, but not everyone uses the Watermill intheir projects. Moreover, 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 framework-agnostic code.
• supports moreprotocols and more specific AsyncAPI entities, such asbindings, correlation ids, server variables, etc.
• has built-in clients for all supported protocols based on popular libraries, that may be used in the generated code.
• is written in Go, so no need to have node.js or Docker or similar tools to run the generator.
• can produce IaC files and build the no-code client application.

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.

Just open an issue or a pull request in theGitHub repository

• https://github.com/asyncapi/generator (official generator)
• https://github.com/lerenn/asyncapi-codegen
• https://github.com/c0olix/asyncApiCodeGen