The Practical Developer

Spec-Driven API Development With OpenAPI: How To Stop Drifting From Your Docs

October 13, 2023 by The Practical Developer

Most teams write the API, then write the OpenAPI spec, then watch them diverge until the docs are useless. The fix is to make the spec the source of truth — generate types, validation, mocks, and clients from it. Here is the workflow that survives, and the tools that make it tractable.

api

openapi

productivity

A developer at a screen — the right setting for API design before implementation

The team ships a new endpoint Tuesday. The OpenAPI spec gets updated Friday. The frontend type definitions get regenerated next sprint. By the end of the quarter, the spec is wrong about three fields, the docs page lies, and the autocompleted SDK calls fail at runtime.

Spec drift is the default state of API development unless you actively prevent it. The fix is to flip the order: write the spec first, generate everything from it. Server validation, client SDK, types, mocks, docs — all derived from one document. Code that doesn’t match the spec doesn’t compile.

This post is the spec-first workflow that holds up in production, the tooling that makes it tractable, and the four traps that revert teams to “code first, spec later.”

What “spec first” actually means

The OpenAPI document is the contract. Before writing endpoint code, you write (or revise) the YAML. The rest is generated:

                ┌──→  Server code (handlers stubbed, validation generated)
                ├──→  Server types (TypeScript / Go structs)
spec.yaml  ─────┼──→  Client SDK (typed methods)
                ├──→  Mock server (responds with example payloads)
                ├──→  Documentation site
                └──→  Contract tests

When the spec changes, regenerate. The compiler tells you what code is now broken. You fix it. Until then, no PR merges with a divergent spec because the build fails.

This is genuinely different from “we have an OpenAPI file in the repo.” That file is a static document that nobody enforces. A spec-driven project enforces it.

The minimal toolchain

For a TypeScript stack, three tools cover the workflow:

1. Spec authoring. Write OpenAPI 3.1 in YAML. Use a linter — Spectral — to catch errors before they get into the repo.

# .spectral.yaml
extends: [[spectral:oas, all]]
rules:
  operation-operationId: error
  operation-description: error

2. Type generation. openapi-typescript generates TS types from the spec.

npx openapi-typescript spec.yaml -o types/api.ts

You get paths['/users/{id}']['get']['responses']['200']['content']['application/json'] types — verbose but accurate.

3. Client SDK. openapi-fetch is a thin, fully-typed client built on the generated types:

import createClient from 'openapi-fetch';
import type { paths } from './types/api';

const client = createClient<paths>({ baseUrl: 'https://api.example.com' });
const { data, error } = await client.GET('/users/{id}', {
  params: { path: { id: '42' } },
});

Type errors at compile time if the spec doesn’t match what you call.

Server-side validation generation

For server-side, fastify has built-in OpenAPI integration that validates requests against the spec at runtime. For Express, express-openapi-validator does the same:

import * as OpenApiValidator from 'express-openapi-validator';

app.use(OpenApiValidator.middleware({
  apiSpec: './spec.yaml',
  validateRequests: true,
  validateResponses: true, // catches handler bugs in dev
}));

Now any request that doesn’t match the spec gets a 400 before reaching the handler. Any response that doesn’t match throws in dev. Your handler cannot drift from the spec without a test failing.

For NestJS, @nestjs/swagger generates OpenAPI from decorators — code-first, but with strong type enforcement. Either direction works as long as the spec is the source of truth.

Mock server from spec

Before the backend is built, the frontend can develop against a mock server that responds with example payloads from the spec:

npx @stoplight/prism mock spec.yaml
# Server runs on localhost:4010 returning example responses.

Prism reads examples and default values from the spec and serves them. Frontend devs can build against this mock for weeks before backend is ready, with confidence that the contract will match.

The repo layout that works

api/
├── spec.yaml                  # source of truth
├── .spectral.yaml             # linting rules
└── examples/                  # request/response samples
src/
├── types/api.ts               # GENERATED — do not edit
├── handlers/                  # implements operations from spec
└── client/                    # GENERATED SDK if you ship one

Generated files are gitignored or committed with a header comment that says “do not edit.” Regeneration is part of npm run build so the repo cannot drift.

A pre-commit hook re-runs generation if the spec changed:

{
  "lint-staged": {
    "spec.yaml": ["spectral lint", "npm run gen:types"]
  }
}

The four traps

1. Spec written after the code. The “code first, then write the spec” workflow drifts from day one. Even if you generate the spec from code (NestJS swagger decorators), the spec must be reviewed in PRs as if it were the source. Otherwise you have docs nobody reads.

2. additionalProperties: true everywhere. A loose spec that accepts any extra fields makes validation useless. Use additionalProperties: false on objects that should be strict; document deliberate extension points explicitly.

3. No examples. Without examples, the spec is pure schema. Mock servers return empty objects, docs are uninformative. Add at least one realistic example per endpoint.

4. type: object with no properties. “It’s just a JSON object” is the same as “this field has no type.” Either describe the shape or call it additionalProperties: { type: string } with a comment about why it’s free-form.

Versioning the API

Two strategies. Either is fine; pick one and stick with it.

Path versioning. /v1/users, /v2/users. The spec has both versions. Old clients keep working until you decide to deprecate.

Header versioning. Accept: application/vnd.example.v2+json. Looks cleaner; harder to debug with curl. Less common in practice.

For breaking changes, use path versioning unless your team has very strong preferences. The deprecation cycle: ship v2, mark v1 deprecated in the spec (deprecated: true), monitor v1 usage, drop v1 when usage hits zero or your sunset date.

See the SemVer post for the deprecation playbook applied to API contracts.

Contract testing

Even with spec-driven dev, you want tests that actually call the API and validate the response. Pact is the standard contract-testing framework — but for a single team owning both client and server, a simpler pattern is enough:

import { test } from 'vitest';
import OpenApiResponseValidator from 'openapi-response-validator';

const spec = loadSpec('./spec.yaml');

test('GET /users/42 matches spec', async () => {
  const res = await fetch('http://localhost:3000/users/42');
  const body = await res.json();

  const validator = new OpenApiResponseValidator({
    responses: spec.paths['/users/{id}'].get.responses,
    components: spec.components,
  });
  const error = validator.validateResponse(res.status, body);
  expect(error).toBeUndefined();
});

This test fails if the response shape diverges from what the spec says it should be. Run in CI; fail the build.

When the spec is internal

If your API is internal (not exposed to third parties), you may not need the full OpenAPI ceremony. The lightest-weight version: TypeScript types defined alongside the handler, the same type imported by the client. No spec file, no codegen.

The spec-driven approach pays off when:

  • The API has external consumers (mobile apps, SDKs, partners).
  • The team is large enough that handler authors and client authors don’t coordinate daily.
  • The API surface is broad enough that drift will happen.

For small internal APIs, type-sharing via a monorepo is enough.

Tools worth knowing

  • Stoplight Studio: visual OpenAPI editor.
  • Redocly: doc generation, linting, CLI.
  • orval: client + mock generation for React/Vue/Angular.
  • Zod-to-OpenAPI: write Zod schemas, generate the spec from them. Useful in code-first projects.

For most Node/TS projects, the combination of openapi-typescript, openapi-fetch, and Spectral covers 90% of what you need.

The takeaway

The spec is the contract. The code conforms to the spec, the client conforms to the spec, the docs are the spec. Generate types, SDKs, mocks, validators from one document; check it in CI. Spec changes are reviewed like API changes (because they are). Run a mock server for parallel frontend development.

The workflow takes a couple of days to set up and pays back the moment somebody discovers that the production API actually matches what is documented. The next time a frontend dev says “the docs are wrong,” you will not have to fix the docs — you will have already broken the build.

A note from Yojji

The kind of API-engineering discipline that keeps the contract and the implementation in sync — spec-first development, generated types, runtime validation, mock servers — is the kind of detail Yojji’s teams build into the platforms they ship for clients.

Yojji is an international custom software development company founded in 2016, with teams across Europe, the US, and the UK. They specialize in the JavaScript ecosystem (React, Node.js, TypeScript), cloud platforms (AWS, Azure, GCP), and full-cycle product engineering — including the API design and contract management that decides whether downstream consumers can trust your endpoints.