DEV Community

myougaTheAxo
myougaTheAxo

Posted on

Design API Contract-First Development with Claude Code: OpenAPI, TypeScript Generation, Mocks

#claudecode #typescript #openapi #testing

Introduction

'Frontend and backend types don't match' — API Contract-First writes OpenAPI spec first, auto-generates TypeScript types, validation, and mocks. Let Claude Code design this.

CLAUDE.md Rules 

## API Contract-First Rules
1. Write OpenAPI 3.1 spec first
2. Auto-generate TypeScript types
3. Auto-apply Express/Fastify validation
4. Prism mock server for frontend parallel dev
- Spec is single source of truth (no drift allowed)
Enter fullscreen mode Exit fullscreen mode

Generated Implementation 

# api/openapi.yaml
openapi: "3.1.0"
paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
Enter fullscreen mode Exit fullscreen mode 
// Auto-generated types from OpenAPI
import type { components } from '../generated/api';
type CreateOrderRequest = components['schemas']['CreateOrderRequest'];

export const CreateOrderRequestSchema = z.object({
  items: z.array(z.object({
    productId: z.string().uuid(),
    quantity: z.number().int().min(1).max(100),
  })).min(1),
});

router.post('/orders', requireAuth, validate(CreateOrderRequestSchema), createOrderHandler);
Enter fullscreen mode Exit fullscreen mode 
# Mock server for frontend parallel development
prism mock api/openapi.yaml --port 4010
Enter fullscreen mode Exit fullscreen mode

Summary

  1. openapi-typescript: auto-generate TypeScript types from spec
  2. Prism mock: frontend can start development before backend is ready
  3. Dredd in CI: verify implementation matches spec
  4. Zod validation: request validation from OpenAPI schema

Review with **Code Review Pack (¥980)* at prompt-works.jp*

myouga (@myougatheaxo) — Axolotl VTuber.

Top comments (0)