OpenAPI Code Generator

Mon, 08 Jun 2026 00:00:00 +0000

Overview

Two generators run in sequence against a single OpenAPI spec:

Generator	Owns	Output
`oapi-codegen`	Types, enums, nested structs, optional pointers	`generated/types.go`
`gen/main.go`	Per-tag interfaces, route registration, strict glue	`generated/interfaces.go`, `routes.go`, `routes.go`, `requests.go`

The result is a clean boundary: generated code you never touch, and handler files you fully own.

Prerequisites

make install-tools

Installs oapi-codegen into $(go env GOPATH)/bin.

Project layout

spec/
  api.yaml              ← source of truth, edit this

cfg/
  types.yaml            ← oapi-codegen config (types only)

gen/
  main.go               ← custom splitter — generates per-tag interfaces + routes

generated/              ← never edit, safe to delete and rebuild
  types.go
  interfaces.go
  routes.go
  requests.go           ← strict mode only

server/
  middleware/           ← hand-written
  handlers/             ← hand-written, implement generated interfaces
  server.go             ← wires router + middleware + handlers

Makefile

Usage

Standard mode