It also includes a CORS bug where my server logged every request and the browser still showed nothing. That one gets its own section.

Why generate the server at all?

The contract is the only thing my wife’s frontend and my backend share. If the Go handlers are written by hand, they’ll drift from the spec sooner or later: a renamed field, a missing status code, a query parameter parsed as the wrong type. With a generated server, the handlers implement an interface that comes straight from the spec. When the spec changes, I regenerate, and the compiler tells me exactly what’s out of date.

Step 1: Choose the server and generate it from the spec

Commit: api: generate Go server and types from the OpenAPI spec

chi

I picked chi as the router:

• I’ve used it before, so it’s one less new thing.
• It’s a thin layer on top of net/http. Handlers are plain http.Handlers, and anything from the standard library works with it.
• It has a good community and plenty of middleware and packages, including the CORS package that shows up later in this post.

oapi-codegen

oapi-codegen turns the bundled spec into Go code. I generate four files, each from its own small config:

The strict server is the important part. Instead of func(w http.ResponseWriter, r *http.Request), each operation becomes a method with typed input and typed output:

func (s server) GetHealth(ctx context.Context, request api.GetHealthRequestObject) (api.GetHealthResponseObject, error)

The generated code parses the path, query, headers and body, calls my method, and writes the response. My code never touches http.Request. The return type is an interface that the generated per-status response types implement, so returning a response the spec doesn’t define takes deliberate effort instead of happening by accident.

Empty string or no field at all?

A few years ago I worked with code generated from proto3 messages with plain string fields. Without the optional keyword (generally available only since protobuf 3.15) or wrapper types like StringValue, proto3 can’t tell the difference between a client sending "title": "" and not sending title at all. Both arrived as an empty string. For a PATCH endpoint that’s a real problem: “clear the excerpt” and “don’t touch the excerpt” look the same.

oapi-codegen handles this the Go way. Optional fields become pointers:

type PostUpdate struct {
	Body    *string     `json:"body,omitempty"`
	Excerpt *string     `json:"excerpt,omitempty"`
	Slug    *string     `json:"slug,omitempty"`
	Status  *PostStatus `json:"status,omitempty"`
	Tags    *[]string   `json:"tags,omitempty"`
	Title   *string     `json:"title,omitempty"`
}

nil means “not sent”, and a pointer to "" means “set it to empty” (for excerpt and body; title has minLength: 1). That’s exactly what the PATCH semantics need.

One caveat: an explicit "excerpt": null also decodes to nil, so “not sent” and “sent as null” look the same. That’s fine here because none of these fields are nullable. If I ever need the difference, oapi-codegen’s nullable-type output option generates nullable.Nullable[T] for it.

Tools pinned with go tool

My first version installed the generator with go install ...@latest. That works on my machine today, but it means anyone cloning the repo next year gets a different generator than the one that produced the committed code.

Since Go 1.24, go.mod can track tools the same way it tracks dependencies:

tool (
	github.com/air-verse/air
	github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen
)

Now go tool oapi-codegen always runs the exact version in go.mod, and the root Makefile uses it:

openapi-generate-go:
	cd api && go tool oapi-codegen --config=../openapi/oapi-codegen/server.yaml ../openapi/dist/openapi.bundled.yaml

The trade-off is that the tools’ dependencies show up in go.mod as indirect requirements. They don’t end up in the API binary, but the file gets longer. I’m fine with that in exchange for one source of truth for versions.

Step 2: Config, stubs and a health check

Commit: api: add server skeleton with config, stub handlers and health check

Config from the environment

Config comes from environment variables, mapped onto structs with go-envconfig. Each package owns its own config struct, and the top-level config just composes them:

// internal/server/config.go
type Config struct {
	Addr              string        `env:"SERVER_ADDR, default=:8080"`
	ShutdownTimeout   time.Duration `env:"SERVER_SHUTDOWN_TIMEOUT, default=30s"`
	ReadHeaderTimeout time.Duration `env:"SERVER_READ_HEADER_TIMEOUT, default=5s"`
	// ...
}

// internal/config/config.go
type Config struct {
	Server *server.Config
}

When the database and auth packages arrive, they’ll add their own Config next to their code instead of one giant struct growing in a single file.

There’s also a test that loads the config with no SERVER_* variables set and compares it with the expected defaults. It sounds trivial, but it’s already caught me twice: once when I added the CORS and timeout fields, and once when I lowered a timeout default. Defaults are part of the behaviour, so they deserve a test. It also makes me look at .env.example every time a default changes, so the code and the docs don’t drift apart.

main.go

main.go stays small: load the config, build the generated handler, wrap it, and run an http.Server with timeouts and graceful shutdown:

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()

cfg := config.New(ctx)

serverInterface := api.NewStrictHandlerWithOptions(server.New(), server.NewServerMiddlewares(), server.NewServerOptions())
handler := api.HandlerWithOptions(serverInterface, api.ChiServerOptions{BaseURL: "/api/v1"})

On SIGINT or SIGTERM the server stops accepting new connections and gives in-flight requests up to SERVER_SHUTDOWN_TIMEOUT to finish.

501 for everything that isn’t built yet

The generated interface has 17 methods, and I’ve implemented one. The stubs for the rest started out as panic("implement me"). Go’s HTTP server recovers from the panic, but the client gets a dropped connection and my log gets a stack trace. Not great when the docs page has a “Try it” button.

501 Not Implemented is the honest answer. The catch is that the strict server only lets a method return the responses the spec defines, and the spec has no 501. It doesn’t need one, though: any error a method returns goes to a configurable ResponseErrorHandlerFunc. So every stub returns a sentinel error:

var ErrNotImplemented = errors.New("not implemented")

func (s server) ListPosts(ctx context.Context, request api.ListPostsRequestObject) (api.ListPostsResponseObject, error) {
	return nil, ErrNotImplemented
}

and the error handler maps it to a status code and writes a problem+json body using the Problem type generated from the spec:

func responseErrorHandler(w http.ResponseWriter, r *http.Request, err error) {
	status := http.StatusInternalServerError
	if errors.Is(err, ErrNotImplemented) {
		status = http.StatusNotImplemented
	} else {
		log.Printf("%s %s %s", r.Method, r.URL.Path, err)
	}

	writeProblem(w, status)
}

A nice side effect: real errors returned from handlers now also come back as a clean 500 in the same format, and the internal error message is logged instead of being sent to the client. Request-decoding errors still get oapi-codegen’s default plain-text 400 for now.

$ curl http://localhost:8080/api/v1/posts
{"status":501,"title":"Not Implemented","type":"about:blank"}

Health check

GET /api/v1/healthz returns {"status":"OK"}. That’s a stub for now. Once there’s a database, it’ll check that the app’s dependencies are reachable and healthy, so Docker and any future deployment can tell a running process from a working one.

Step 3: One command for the whole dev environment

Commit: tooling: add Docker Compose dev environment

docker compose up starts three services:

The api container mounts the source code and runs go tool air, so Air is pinned in go.mod like the generator. Two named volumes keep the Go module cache and the build cache (which holds the compiled Air binary) between container restarts. Without them, every recreated container downloaded all modules and compiled Air from scratch before serving a single request.

Do I still need Prism?

While setting this up, I noticed that the Redocly preview also has a built-in mock server behind its “Try it” console. So is Prism redundant?

Not for us. The Redocly mock is great for trying endpoints from the docs page. Prism is a standalone server on a fixed port that the React app can use as its backend while my endpoints are still returning 501. It also validates requests against the spec and supports the Prefer header, so the frontend can ask for a specific response, like Prefer: code=412 for the edit-conflict case. That’s what the frontend needs, so Prism stays.

Step 4: The request that arrived and never came back

Commit: api: add CORS middleware

With everything running, I opened the docs on localhost:8081, pointed the “Try it” console at my real API on localhost:8080, and called the health check. The API logged the request. The docs page showed no response at all.

Part one: CORS

The server did its job. The browser threw the response away.

A different port is a different origin, so a page on :8081 calling :8080 makes a cross-origin request. A plain GET without custom headers is a “simple” request, so the browser sends it straight away without a preflight. My handler runs and returns 200. But the response has no Access-Control-Allow-Origin header, so the browser refuses to let the page read it. The devtools console says so, if you think to look there.

The fix is the go-chi/cors middleware. One detail matters: it has to run before chi’s routing, so I wrap the whole handler at the net/http level instead of adding it to the strict server’s middleware list. A preflight OPTIONS request doesn’t match any generated route (chi answers 405 or 404 itself), so per-operation middleware never sees it.

handler = cors.Handler(cors.Options{
	AllowedOrigins:   cfg.Server.AllowedOrigins,
	AllowedHeaders:   cfg.Server.AllowedHeaders,
	AllowedMethods:   cfg.Server.AllowedMethods,
	AllowCredentials: cfg.Server.AllowCredentials,
})(handler)

Part two: * means “all methods” in the spec, but not in go-chi/cors

I added CORS, set everything to * in my local env to get going, and still got nothing.

Calling the API with curl and an Origin header showed the middleware was running, since the response had Vary: Origin, but there was still no Access-Control-Allow-Origin.

That surprised me, because * is a valid value for the Access-Control-Allow-Methods header: for requests without credentials, it means “all methods”. The protocol was fine; the library was the problem. Reading the go-chi/cors source explained it. In its options, * is a wildcard for AllowedOrigins and AllowedHeaders, but not for AllowedMethods. There, * is compared literally against the request method, as if it were a method called *.

On top of that, go-chi/cors checks the method on the actual request too, not only on the preflight, which the CORS spec doesn’t ask for. My GET was a simple request with no preflight, and GET wasn’t in my list, so it got no CORS headers at all. A preflighted request wouldn’t have fared better: the preflight checks the requested method against the same list, and on a mismatch it still answers 200 OK, just without any CORS headers.

Even a library that passed * through wouldn’t have saved this config, because I also had AllowCredentials: true. For requests with credentials (cookies, TLS client certificates or HTTP authentication), browsers treat * in Access-Control-Allow-Methods and Access-Control-Allow-Headers as a literal name. That setting had a problem of its own, which is part three.

Listing the methods explicitly fixed it:

SERVER_ALLOWED_METHODS="GET,POST,PUT,PATCH,DELETE,OPTIONS"

Part three: don’t ship the permissive version

While I was there, I noticed a config that only worked by accident. AllowedOrigins: * with AllowCredentials: true makes go-chi/cors send Access-Control-Allow-Origin: * next to Access-Control-Allow-Credentials: true, a combination browsers reject for credentialed requests. MarginCMS uses bearer tokens and no cookies, so it doesn’t need credentials at all, and there’s no reason to let every origin in either. The defaults are now strict:

AllowedOrigins   []string `env:"SERVER_ALLOWED_ORIGINS, default=http://localhost:8081"`
AllowedMethods   []string `env:"SERVER_ALLOWED_METHODS, default=GET,POST,PUT,PATCH,DELETE,OPTIONS"`
AllowedHeaders   []string `env:"SERVER_ALLOWED_HEADERS, default=Authorization,Content-Type"`
AllowCredentials bool     `env:"SERVER_ALLOW_CREDENTIALS, default=false"`

If it works locally with *, that’s a sign to tighten it, not a sign that you’re done.

What I’d tell myself before starting

• When the server says 200 and the client sees nothing, the browser is the one dropping the response. Start debugging there.
• Read the source of small middleware packages. go-chi/cors is a few hundred lines, and five minutes of reading beat an hour of guessing.
• Pin your code generators. Generated code is only reproducible if the generator version is.
• Test your defaults. It’s the cheapest test you’ll write and it keeps config and docs honest.

Next steps

1. Add a linter. golangci-lint with a config that’s strict from day one, while there’s still almost no code to fix.
2. Start on auth with mock data. Login, token refresh, logout and GET /me, backed by an in-memory user for now, so the auth flow and its tests exist before the database does.

This first part covers why I’m doing it, and the work that happened before writing any Go code: the API contract, the tooling around it, and the plan for the backend.

The code is public at github.com/davidporos92/margin-cms.

Why build a CMS in 2026?

Nobody needs another CMS, including me. I’m building one anyway, for four reasons.

It’s fun. Writing a CMS has been on my someday list for years, and a pet project with no deadline and no users is the best place to finally do it.

Deliberate practice. I use AI tools every day, and they’re good. But I noticed I reach for them before I’ve thought a problem through. I want one project where I make every decision and write the code myself, with AI as a reviewer and a rubber duck rather than the author.

It starts easy and gets hard. A CMS starts as CRUD over a posts table, which is a nice way to ease back in. Then the real problems show up: authentication and token refresh, revision history, two people editing the same post at the same time, search, pagination. Each of these is small enough to finish and deep enough to learn something from.

There’s a lot of room to grow. Once the core works, there’s room for tools, plugins and packages around it: an export pipeline to my existing blog, a CLI, maybe a client library. None of that is planned yet, but the option is there.

My wife is building the React frontend, so this is a two-person project with a clean split: I own the Go API, she owns the web app and the design system. The only thing we share is the API contract (and a small little doggo), and that shapes almost every decision below.

The scope, briefly

To keep it finishable, v1 is deliberately boring:

• one admin user, one content type (posts), no media uploads, no plugin system
• posts are markdown with a title, slug, excerpt, tags and a status (draft, published, archived)
• every content change creates a revision, and an activity log records who did what
• one Go binary with small internal packages (auth, posts, revisions, activity, stats)

“Modular” here means compile-time packages with small interfaces, not a dynamic content-type builder.

Step 1: Write the OpenAPI contract first

Commit: Add OpenAPI contract and spec tooling

Before writing a single handler, I wrote the API as an OpenAPI 3 spec. That had two goals.

Don’t block the frontend. If the frontend has to wait for my endpoints, it’ll wait a long time. With a spec in place, the frontend can generate its TypeScript types and develop against a mock server from day one, and switch the base URL once the real endpoints land.

Get a clear picture of what I’m building. Writing the contract forced decisions I would otherwise have made halfway through a handler:

• Auth: a short-lived access token in Authorization: Bearer, plus a single-use refresh token. No cookies, so classic CSRF doesn’t apply; XSS is the thing to guard against instead.
• Errors: every error is application/problem+json (RFC 9457), with field-level details for form validation.
• Optimistic concurrency: posts carry an ETag, and updates, deletes and revision restores require If-Match. A stale write gets 412 Precondition Failed with the current version of the post in the response, so the UI can show a proper conflict banner instead of silently overwriting someone’s work.
• Pagination: cursor-based, not offset-based.

The result is 17 operations across auth, posts (including bulk actions and markdown export), revisions, tags, activity, stats and a health check.

I didn’t want one 2,000-line YAML file, so the spec is split into small files: one per path and one per component (schemas, parameters, request bodies, responses), all referenced from a root openapi.yaml. The convention is simple: file name equals component name. components/schemas/Post.yaml defines Post. A bundler merges everything into a single file for the tools that need one.

Step 2: Set up tooling around the spec

A spec is only useful if the tooling around it is easy to use, so the same commit adds npm scripts and make targets for:

Prism deserves a special mention. Besides returning example responses, it supports the Prefer header. The frontend can send Prefer: code=412 and get a 412 back, which makes it possible to build the conflict handling long before the backend can produce a real conflict.

Step 3: Plan the Go backend

No commit for this one. It’s the thinking that happened before the code.

I picked tools in three groups.

The HTTP server. I went with chi. I’ve used it before, it stays close to net/http, and oapi-codegen can generate a chi server directly from the spec. More on that in part 2.

Data access. The classic Go debate is ORM versus plain SQL. Since part of the point is to learn new things while I ease back into Go, I chose tools I haven’t used in anger yet:

• PostgreSQL with pgx
• Ent for the schema and data access, with the schema written as Go code
• Atlas to generate versioned SQL migrations from the Ent schema. The API never changes the database schema on its own.
• testcontainers-go for integration tests against a real Postgres, using the same migration files that ship

Code generation from OpenAPI. Handlers implement an interface generated from the spec, so the code can’t drift from the contract without the compiler noticing.

Step 4: Plan the local dev setup

Also mostly planning at this stage. The goal was a dev loop where everything runs with one command:

• Go hot reload with Air, so saving a file rebuilds and restarts the API
• Prism as the mock backend for the web app, for the Prefer header support mentioned above
• Docker Compose so we both get the same environment, including Postgres later

Next steps

In part 2 I set up the Go service and the local environment: generating the server from the spec, config handling, stub handlers, the Docker Compose setup, and a CORS bug that turned out to be a library quirk, not the protocol.