gen-asyncapi

README

gen-asyncapi

Feed it an AsyncAPI 3 document and it spits out Go or TypeScript types, strict JSON decoding and a client for your WebSocket API. Run it from go generate with a small config file and the path to your spec, and the generated file lands next to your code.

Decoding is strict. A frame either matches its schema or you get an error that names every message it tried and why each one said no.

Spec loading comes from go-asyncapi. Grab that one directly if you want to read AsyncAPI 3 documents in Go without generating anything.

Contents

• Install
• Quick start
• Documentation
• Agent integrations
• Development
• Sponsor
• License

Install

go install github.com/psyb0t/gen-asyncapi/cmd/gen-asyncapi@latest

As a Go tool in your module, so go tool gen-asyncapi runs the version your go.mod pins:

go get -tool github.com/psyb0t/gen-asyncapi/cmd/gen-asyncapi@latest

A TypeScript project needs no Go module, just Go installed: Install and run has the go run line.

Quick start

Drop a config.yaml and a gen.go where the code should go:

# config.yaml
package: chat
output: chat.gen.go

// gen.go
package chat

//go:generate go tool gen-asyncapi --config=config.yaml ../../api/asyncapi.yaml

Run go generate ./... and chat.gen.go appears, with a struct per schema, strict UnmarshalJSON and Validate, a Handler for incoming messages and a Client with one method per outgoing one:

conn, err := gorillaws.Dial(
	ctx,
	chat.ServerProductionURL,
	gorillaws.WithBearerToken(token),
)
if err != nil {
	return err
}

client := chat.NewClient(conn)
defer client.Close()

err = client.JoinRoom(ctx, chat.JoinRequest{ID: id, Room: "lobby"})

Add -language=typescript -o=chat.gen.ts and the same spec turns into one dependency-free .ts file whose client takes a browser WebSocket.

Documentation

The full documentation lives at https://psyb0t.github.io/gen-asyncapi/.

Page	What it covers
Install and run	Install routes, the command line, go generate, logging, upgrades
Configuration	Every config key, its default and what fails validation
Go output	Structs, enums, unions, sending and receiving in Go
TypeScript output	Interfaces, validators and the browser client
Message matching	How incoming frames are told apart, and message-matchers
What gets generated	Each spec part and what it becomes in both languages
AsyncAPI 3 coverage	Every AsyncAPI object and schema keyword, one row each
Example packages	The committed examples and what each one proves
Agent integrations	The agent skill for Claude Code, Codex and OpenClaw
Troubleshooting	Generator errors and runtime decoding errors, with fixes
Development	Make targets, the dev image, CI and releases

Agent integrations

The skill teaches a coding agent how to set up the generator and use the code it writes, in Go and TypeScript:

claude plugin marketplace add psyb0t/agents
claude plugin install gen-asyncapi@psyb0t

Codex and OpenClaw installs are on the Agent integrations page.

Development

Everything runs in the Dockerfile.dev image. You need Docker and Make.

make help           # list targets
make generate       # regenerate the examples
make lint           # shellcheck, shfmt, go fix, golangci-lint
make test-coverage  # go test -race with a 90% coverage gate, then make test-ts
make docs           # build the documentation site into .testing/docs-site

Development covers the rest, including CI and releases. Contributor and agent instructions are in AGENTS.md.

Sponsor

License

MIT. The specs in examples/official come from the AsyncAPI specification repository under Apache 2.0.