OpenAPI generation for REST endpoints

import { Request, Response, NextFunction, RequestHandler } from 'express';
import { ZodError } from 'zod';
import { RouteConfig } from './registry';

function formatIssues(err: ZodError) {
  return err.issues.map((i) => ({
    field: i.path.join('.') || '(root)',
    message: i.message,
  }));
}

export function validateRequest(config: RouteConfig): RequestHandler {
  return (req: Request, res: Response, next: NextFunction) => {
    const targets: Array<[keyof Request, RouteConfig[keyof RouteConfig]]> = [
      ['body', config.body],
      ['query', config.query],
      ['params', config.params],
    ];

    for (const [key, schema] of targets) {
      if (!schema) continue;
      const result = (schema as any).safeParse(req[key as 'body']);
      if (!result.success) {
        return res.status(400).json({
          error: 'ValidationError',
          in: key,
          issues: formatIssues(result.error),
        });
      }
      (req as any)[key] = result.data;
    }

    next();
  };
}

import { Router, Request, Response } from 'express';
import { z } from 'zod';
import { defineRoute } from './registry';
import { validateRequest } from './validate';

export const router = Router();

const CreateUserBody = z
  .object({
    email: z.string().email().openapi({ example: 'ada@example.com' }),
    name: z.string().min(1).openapi({ example: 'Ada Lovelace' }),
    role: z.enum(['admin', 'member']).default('member'),
  })
  .openapi('CreateUserBody');

const UserResponse = z
  .object({
    id: z.string().uuid(),
    email: z.string().email(),
    name: z.string(),
    role: z.enum(['admin', 'member']),
    createdAt: z.string().datetime(),
  })
  .openapi('UserResponse');

const ErrorResponse = z
  .object({ error: z.string(), issues: z.array(z.any()).optional() })
  .openapi('ErrorResponse');

const createUser = defineRoute({
  method: 'post',
  path: '/users',
  summary: 'Create a new user',
  body: CreateUserBody,
  responses: {
    201: { description: 'Created', schema: UserResponse },
    400: { description: 'Invalid payload', schema: ErrorResponse },
  },
});

router.post('/users', validateRequest(createUser), (req: Request, res: Response) => {
  const input = req.body as z.infer<typeof CreateUserBody>;
  const user = {
    id: crypto.randomUUID(),
    ...input,
    createdAt: new Date().toISOString(),
  };
  res.status(201).json(user);
});

import { writeFileSync } from 'node:fs';
import { OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';
import { registry } from './registry';

// Side-effect import: registers every path onto the shared registry.
import './users.routes';

function buildSpec() {
  const generator = new OpenApiGeneratorV31(registry.definitions);
  return generator.generateDocument({
    openapi: '3.1.0',
    info: {
      title: 'Users API',
      version: '1.0.0',
      description: 'Generated from Zod schemas — do not edit by hand.',
    },
    servers: [{ url: 'https://api.example.com/v1' }],
  });
}

const spec = buildSpec();
writeFileSync('openapi.json', JSON.stringify(spec, null, 2));
console.log(`Wrote openapi.json with ${Object.keys(spec.paths ?? {}).length} paths`);