pn-openapi-design

OpenAPI design

When to use

• Designing a new API before writing implementation code (contract-first)
• Generating a spec from existing TypeScript types or Zod schemas
• Producing client SDKs, server stubs, or typed fetch clients from a spec
• Reviewing API design for REST conformance, versioning, or schema consistency
• Setting up interactive API documentation (Swagger UI, Redoc, Scalar)

Core principles

1. Spec is the contract — the OpenAPI document is the authoritative source of truth; implementation must conform to it, not the other way around.
2. Contract-first, not code-first — write or review the spec before writing handlers; this forces deliberate API design and catches breaking changes early.
3. One spec, many consumers — a single spec generates server types, client SDKs, mock servers, and docs; treat it as a build artifact.
4. Explicit over implicit — every field in request/response schemas must have a type, description, and example; avoid additionalProperties: true at boundaries.
5. Version at the URL — use /api/v1/ path prefix; document deprecation notices in info.x-deprecated or x-sunset header.

Workflow

Contract-first with Zod (TypeScript)

// 1. Define schema with Zod
import { z } from "zod";

export const CreateUserBody = z.object({
  email: z.string().email().describe("User email address"),
  name: z.string().min(1).max(100).describe("Display name"),
});

export const UserResponse = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string(),
  createdAt: z.string().datetime(),
});

// 2. Register with zod-to-openapi
import { OpenAPIRegistry, OpenApiGeneratorV31 } from "@asteasolutions/zod-to-openapi";

const registry = new OpenAPIRegistry();

registry.registerPath({
  method: "post",
  path: "/users",
  summary: "Create a user",
  request: { body: { content: { "application/json": { schema: CreateUserBody } } } },
  responses: {
    201: { description: "Created", content: { "application/json": { schema: UserResponse } } },
    422: { description: "Validation error" },
  },
});

// 3. Generate spec
const generator = new OpenApiGeneratorV31(registry.definitions);
const spec = generator.generateDocument({ openapi: "3.1.0", info: { title: "API", version: "1.0.0" } });