Building a web service with go-tool-base, part 5: docs that write themselves
Generate an OpenAPI v3 document from an annotated proto file and serve it from the same HTTPS server with an embedded Stoplight Elements UI.
Categories
78 pages
go-tool-base
The underpinnings for any Go command-line tool, and (as a few of my projects now prove) for comprehensive web services too. It standardises the boilerplate and wiring you end up writing in every Go project, and puts config, logging, self-update, a DI container and the rest straight at your fingertips. Highly opinionated, and it makes some calls people will disagree with, but it works, and it works really well. The CLI it ships with is a big part of that: keeping a Go app built, updated and maintained becomes almost trivial.
Building a web service with go-tool-base, part 4: REST for free, with the gateway
Replace a hand-written REST layer with grpc-gateway: add google.api.http annotations, generate the gateway, and delete the duplicate encoding.
Building a web service with go-tool-base, part 3.5: the same server, now a website
Serve HTML from the same Go HTTP server using html/template and embed, baking templates and static assets straight into the binary.
Building a web service with go-tool-base, part 3: a REST service, by hand and by spec
Two ways to put REST on a Go service: a hand-written net/http ServeMux, and generated handlers from an OpenAPI spec with oapi-codegen.
Building a web service with go-tool-base, part 2: a gRPC service, with TLS
Define a protobuf contract, generate Go with buf, implement a gRPC server over a domain store, and turn on hardened TLS with mkcert and ALPN.
Building a web service with go-tool-base, part 1: lifecycle and graceful shutdown
Service lifecycle in Go: register services with start and stop verbs, handle SIGINT and SIGTERM, and shut down gracefully with liveness checks.
Building a CLI with go-tool-base, part 5: a CLI that updates itself
Add self-update to a Go CLI: resolve releases per platform, compare versions, verify checksums and migrate config on upgrade.
Building a CLI with go-tool-base, part 4: an AI dungeon master
Build an AI dungeon master in Go: keep the model to prose only by putting the rules in the system prompt and the mechanics in typed tool calls.
Building a CLI with go-tool-base, part 3: expose your CLI to AI agents
Expose an existing Go CLI to AI agents over MCP without writing any AI code, using built-in commands. The agent reach equals the CLI reach.
Building a CLI with go-tool-base, part 2: configuration your tool can trust
Configuration for a Go CLI: precedence of flags over env over files, per-command embedded defaults, layered config merging and a strict mode.
