I let my OpenAPI spec do the work: one contract for Go, Flutter, and the LLM

tkode — Sat, 09 May 2026 16:54:08 +0000

There was a period on a Django project where a simple question of "is this field actually used on the frontend?" would trigger a small investigation. You'd check the backend, grep through the React code, and ask someone who might know. The answer was always in there somewhere, but it was never in one place. Not like anyone was being careless. There just wasn't a contract. So every question got answered by digging.

My stack is Go on the backend and Flutter on the frontend. Before I settled on the current approach, adding an endpoint meant the same work twice. Define request and response structs in Go, wire the handler, add middleware. Then repeat the whole model layer in Dart, and build a repository around Dio to actually call it. Every change paid the same tax. Low-grade, but it compounds.

The fix I landed on isn't novel in isolation: generate code from an OpenAPI spec. But the way it fits together took a few projects to get right. The spec isn't documentation. It's the artifact everything compiles against — and the layer where human judgment, compiler enforcement, and LLM reasoning all meet before any implementation happens.

The insight: the spec isn't documentation, it's the artifact

Most OpenAPI content treats the spec as something you generate from code or maintain alongside it. The approach I kept arriving at, across three projects, was the opposite: write the spec first, generate everything from it, and never let code drift from it.

This works because OpenAPI is structured, checkable, and well-represented in LLM training data. When I ask a model to design an endpoint, it writes OpenAPI YAML reliably — better than it writes idiomatic Go or Dart from scratch. That makes the spec a natural handoff point: the human reviews it, the compiler enforces it, and the LLM never touches implementation until the contract is settled.

The first project where I tried this properly was in Flutter. Dart is typed by default, and the friction of keeping Go structs and Dart models manually aligned was obvious from the start. I set up code generation on both sides, and the gap closed. When I started the current project (an institute ERP), this was the natural starting point, not an experiment.

The codegen pipeline

The monorepo structure matters here. Everything lives together because the spec has to be the single source of truth across consumers.

api/
├── services/
│   ├── auth.yaml
│   ├── students.yaml
│   ├── attendance.yaml
│   ├── fees.yaml
│   └── ... (23 service files total)
├── openapi.yaml          ← combined, generated by redocly
├── index/                ← auto-generated navigation for LLMs
├── redocly.yaml
└── scripts/
    └── post-build.js

backend/gen/api/
├── attendance/
│   ├── codegen.yaml
│   ├── generate.go
│   └── schema.gen.go
├── auth/
│   ├── codegen.yaml
│   ├── generate.go
│   └── schema.gen.go
├── fees/
│   ├── codegen.yaml
│   ├── generate.go
│   └── schema.gen.go
└── ... (23 services, mirroring the spec split)

frontend/packages/shared_api_client/lib/
├── attendance/
│   ├── attendance_client.dart        ← generated
│   └── attendance_client.g.dart      ← generated
├── models/
│   ├── attendance_status.dart
│   ├── get_today_attendance_response.dart
│   ├── get_today_attendance_response.freezed.dart
│   ├── get_today_attendance_response.g.dart
│   ├── today_attendance_item.dart
│   ├── today_attendance_item.freezed.dart
│   └── today_attendance_item.g.dart
│   └── ... (400+ model files across all services)
└── export.dart

Each service gets its own YAML file. openapi.yaml is assembled from these by redocly. A post-build.js script handles two things after the build: setting the correct server URLs for hosted documentation, and stripping a handful of empty fields that break swagger-parser downstream. That second task isn't something glamorous, but is a real part of any pipeline like this.

Backend. oapi-codegen generates Go interfaces and types from the spec. The backend mirrors the service split: backend/gen/api/ has a folder per service, each with a config, a generate.go, and a schema.gen.go. I wire these to gin handlers and implement the logic in backend/src/, same folder structure. Running go generate regenerates the backend code when the spec changes. It's intentionally kept as a manual trigger. You run it when you've made a deliberate change to the spec, not on every save.

Frontend. The combined openapi.yaml feeds into swagger-parser with a configuration that splits output by OpenAPI tags and generates frozen Dart classes via freezed. The generated code lives in a shared_api package that both the institute-facing and parent-facing apps consume. Dart tree-shaking handles unused paths.

The components/schemas section from attendance.yaml (API paths excluded for brevity):

AttendanceStatus:
  type: string
  enum:
    - PRESENT
    - ABSENT
    - NOT_SET

TodayAttendanceItem:
  type: object
  required:
    - studentId
    - studentName
    - admissionNumber
    - rollNumber
    - status
  properties:
    studentId:
      type: string
      format: uuid
      x-go-type: uuid.UUID
      x-go-type-import:
        path: github.com/google/uuid
    studentName:
      type: string
    admissionNumber:
      type: string
    rollNumber:
      type: string
    status:
      $ref: '#/components/schemas/AttendanceStatus'
    remarks:
      type: string

GetTodayAttendanceResponse:
  type: object
  required:
    - date
    - items
    - totalCount
  properties:
    date:
      type: string
      example: '2026-03-21'
    items:
      type: array
      items:
        $ref: '#/components/schemas/TodayAttendanceItem'
    totalCount:
      type: integer

Generated Go (schema.gen.go):

Generated Dart (shared_api package):

The x-go-type extension on studentId tells the generator to use uuid.UUID instead of plain string. The Dart side doesn't see it; it gets String, which is correct. One spec, two different type systems, no compromise.

The enforcement layer is the LSP. If the spec changes and codegen runs, any mismatch between how the backend implements an interface and what the spec defines is a type error, caught before the code runs. Same on the Flutter side. It's not a document you can ignore. It's a thing the compiler checks.

The tooling is table stakes. Here's why this setup pays off specifically when working with an LLM.

Agentic coding is why this is worth the setup cost

I use agentic coding heavily on this project. The spec-first approach and the agentic approach reinforce each other in a way that's hard to see until you've hit the alternative.

Without a contract, LLM-generated backend and LLM-generated frontend code drift silently. The model that wrote your Go handler and the model that wrote your Dart repository have no shared ground truth. They make different assumptions about field names, nullable types, error shapes. You find out at runtime, or you don't find out until a user does.

With codegen, drift becomes a compile error.

The loop looks like this: I describe the feature I want, then explicitly ask the agent to update the relevant YAML files first — and nothing else. I review the spec change before proceeding. Only once the contract looks right do I tell the agent to run go generate and continue to the backend implementation and tests. The frontend client is regenerated after the backend is stable — same script, pointed at the combined openapi.yaml. At every step, the generated types are what both sides compile against. If something doesn't line up, the build fails, not the app.

This sequencing is a discipline I maintain deliberately, not an automated constraint. You could enforce it via a CLAUDE.md instruction and get the same result. But the point is the same either way: the human reviews the contract before any implementation happens.

The Flutter side took more iteration to get right, but the principle was the same: let the spec own the types, and let the compiler enforce it.

The index layer: making the truth accessible to an agent efficiently

The spec grew. It's now 23 service files, covering everything from auth to timetable to parent-facing dashboards. Without explicit instructions, an LLM working on a feature would load the entire combined openapi.yaml — large, token-expensive, and mostly irrelevant. Pointing it to service-level specs helped, but only partially. The larger service files are 1000+ lines, and even those contain models unrelated to the task at hand. The agent still had no way to navigate to just what it needed.

So I built a lightweight navigation layer, auto-generated by a Python script and kept up to date via a pre-commit hook. It lives in api/index/ and produces three things: a top-level README with a service summary table; one detail file per service listing its endpoints and the models they use; and a combined models.md covering every model across all services, so an agent can search by model name without knowing which service file to open.

The entry point is a README that gives a high-level service table:

Service	Size	Operations	Backend owner hints	Detail
`admission.yaml`	large (1795)	29	backend/src/admission/	Admission Service
`attendance.yaml`	medium (561)	8	backend/src/attendance/	Attendance Service
`institute.yaml`	small (237)	3	backend/src/institute/	Institute Service
`students.yaml`	large (1760)	18	backend/src/students/	Students Service
...

The guidance in the README: small specs are cheap to read whole, large specs should be read by operation. Each service links to a detail file with an operation table and model index:

Method	Path	Operation ID	Request models	Response models	Summary
`POST`	`/auth/onboarding`	`submitInstituteOnboarding`	OnboardingRequest	`200`: User, `400/401/409/500`: ErrorResponse	Submit institute details (Onboarding Stage 1)
`PATCH`	`/auth/me/institute`	`updateCurrentUserInstitute`	UpdateCurrentUserInstituteRequest	`200`: User, `400/401/403/404/500`: ErrorResponse	Update current user's institute details

An agent looking at a narrow task — say, updating the fees endpoint — doesn't need to load auth.yaml or students.yaml. It looks at the index, navigates to fees.md, finds the operation, and loads only what it needs.

It's still rough in places — the size classification (small, medium, large) is a heuristic, not a formal metric. But a rough heuristic maintained automatically is more reliable than a precise one maintained manually.

The honest tradeoffs

Multi-developer friction. Frontend and backend for a feature have to move together because they share generated types. When you're solo, that's fine. On a team, parallel work on the same service generates conflicts in generated files, and onboarding someone new requires a conversation before they can be productive. There are mitigations (per-service generated clients, stricter spec ownership boundaries), but I haven't needed to solve this yet.

Spec evolution. When an endpoint changes shape: update the spec, regenerate, fix the compile errors. The compile errors are useful: they surface exactly where something is breaking, which sometimes makes it obvious that old clients would be affected. Once that led me to mark a field as deprecated and add a new field alongside it rather than rename in place. The weak part is observability. There's no reliable way to know if old client versions in the wild are still hitting deprecated fields. For this project that's fine, as it's pre-launch. But worth being honest about if you're running something in production.

The swagger-parser error type limitation. The Flutter codegen only produces one response type per endpoint: the success type. All error codes get parsed manually. I've accepted this for now. It could be addressed by extending swagger-parser, but it hasn't been worth the time.

The post-build patching. The fact that post-build.js exists to strip empty fields that break downstream tooling is a real thing. The pipeline works, but it has seams. If you adopt this approach, you'll find your own seams. Budget for them.

What this is actually about

This is a workflow tradeoff: upfront structure in exchange for eliminating a specific category of mechanical toil. The toil it eliminates is model drift: the silent divergence between what your backend says and what your frontend expects. In an agentic workflow, that divergence happens faster and is harder to catch. The spec doesn't prevent LLMs from making mistakes. It just means a certain class of them — type mismatches, missing fields, inconsistent response shapes — become compile errors instead of bugs.

The core of it — one spec, three consumers, everything compiled against the same ground truth — has been stable across multiple projects. That stability is what I was actually looking for. The index layer and the error type handling are still evolving; I'll write about those when there's more to say.

Resources

oapi-codegen — Go code generation from OpenAPI specs
package main: Practical OpenAPI in Go — the video that started the Go side of this for me

DEV Community: tkode