Spec-first Golang project scaffold generator
- OpenAPI first – start with a spec, everything else is generated around it.
- Code generation with [ogen-go/ogen] – generation of request/response models & router.
- Dependency injection via [rom8726/di] – constructor-based DI.
- Batteries included
- PostgreSQL integration
- MySQL integration
- MongoDB integration
- Redis integration (optional)
- Kafka integration (optional)
- Memcache (optional)
- Etcd (optional)
- Aerospike (optional)
- ElasticSearch (optional)
- Nats (optional)
- RabbitMQ (optional)
- Database migrations support
- Database transactions manager (PostgreSQL and MySQL)
- Library for working with Kafka
- Testy [rom8726/testy] integration needed code for functional tests (for PostgreSQL and MySQL)
- Health-check, Prometheus metrics, pprof endpoints
- Structured logging with slog
- Docker-ready –
Dockerfile,docker-compose.yml,Makefileare scaffolded for you. - Static analysis out of the box –
.golangci.ymlwith commonly used linters. - CLI powered by [spf13/cobra]
- 12-factor config – environment variables parsed with
envconfig,.envsupported.
# Install the generator binary
go install github.com/rom8726/airo/cmd/airo@latest
# Run the TUI
airo generateThe wizard will ask:
- Project name (folder will be created in the current directory)
- Go module path (e.g.
github.com/acme/myservice) - Path to OpenAPI specification (YAML or JSON)
- Database choice (PostgreSQL \ MySQL \ MongoDB)
- Additional infrastructure (Redis \ Kafka)
Screenshots:
After confirmation, the scaffold is generated.
Infrastructure-specific sections (PostgreSQL container, Redis container, volumes, healthchecks, etc.) are automatically injected into docker-compose.yml.
If you don’t have a spec yet, start with the included template example/server.yml or something like this:
openapi: 3.1.0
info:
title: Example API
version: 1.0.0
paths:
/ping:
get:
summary: Ping-pong endpoint
operationId: ping
responses:
'200':
description: pong
content:
text/plain:
schema:
type: stringmyservice/
├── cmd/
│ └── server/ # server command
├── internal/
│ ├── api/
│ │ └── rest/ # your handlers (interfaces generated by ogen)
│ ├── generated/ # ogen output (do not edit)
│ ├── config/ # env-config structs & helpers
│ └── app.go # app, db, redis, etc.
├── pkg/ # reusable packages
├── dev/
│ ├── docker-compose.yml # app + selected infra (PostgreSQL, Redis…)
│ ├── compose.env.example # config file example for docker compose environment
│ ├── config.env.example # config file example for local environment
│ └── dev.mk # Makefile commands for operate docker compose
├── main.go
├── .golangci.yml # linter configuration
├── Dockerfile # multi-stage build (scratch runtime)
├── Makefile # common targets: build, run, test, lint, etc.
└── go.mod
Create/adjust .env (or pass variables directly):
API_SERVER_ADDR=:8080
TECH_SERVER_ADDR=:9090
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secret
POSTGRES_HOST=localhost:5432
POSTGRES_DATABASE=mydb
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0cd myservice
go run ./cmd/server --env-file=.envMost repetitive commands are wrapped into make targets:
# Build the binary for your host
make build
# Run unit tests & linters
make test # go test ./...
make lint # golangci-lint run
# Build container image and start entire stack
make dev-up # equivalent to: docker compose upmake dev-up relies on the generated docker-compose.yml.
Only the services you selected in the wizard will be present (e.g. if you skipped Redis, the file will contain only the app + PostgreSQL).
Stop and clean resources:
make dev-down # docker compose downGET :8080/ping– from your OpenAPI specGET :8081/health– liveness probeGET :8081/metrics– Prometheus metricsGET :8081/debug/pprof/*– pprof profiles
Apache-2.0 License