OpenAPI & Swagger

// Code-first with @asteasolutions/zod-to-openapi (pattern)
import { OpenAPIRegistry, OpenApiGeneratorV3 } from "@asteasolutions/zod-to-openapi";
import { z } from "zod";
 
const registry = new OpenAPIRegistry();
const OrderSchema = z.object({ id: z.string(), status: z.string() }).openapi("Order");
 
registry.registerPath({
  method: "post",
  path: "/v1/orders",
  responses: { 201: { description: "Created", content: { "application/json": { schema: OrderSchema } } } },
});
 
const doc = new OpenApiGeneratorV3(registry.definitions).generateDocument({
  openapi: "3.0.3",
  info: { title: "Orders API", version: "1.0.0" },
});

# Serve UI in dev only
npm install swagger-ui-express

// src/openapi/document.ts
import { z } from "zod";
import {
  OpenAPIRegistry,
  OpenApiGeneratorV3,
  extendZodWithOpenApi,
} from "@asteasolutions/zod-to-openapi";
 
extendZodWithOpenApi(z);
 
const registry = new OpenAPIRegistry();
 
export const CreateOrderBody = z
  .object({
    customerId: z.string().uuid(),
    sku: z.string(),
    qty: z.number().int().positive(),
  })
  .openapi("CreateOrderBody");
 
export const Order = z
  .object({
    id: z.string(),
    customerId: z.string().uuid(),
    sku: z.string(),
    qty: z.number(),
    status: z.enum(["pending", "shipped"]),
  })
  .openapi("Order");
 
registry.registerPath({
  method: "post",
  path: "/v1/orders",
  tags: ["Orders"],
  request: { body: { content: { "application/json": { schema: CreateOrderBody } } } },
  responses: {
    201: {
      description: "Order created",
      content: { "application/json": { schema: z.object({ data: Order }) } },
    },
    400: { description: "Validation error" },
  },
});
 
export function generateOpenApiDocument() {
  return new OpenApiGeneratorV3(registry.definitions).generateDocument({
    openapi: "3.0.3",
    info: { title: "Acme Orders API", version: "1.0.0" },
    servers: [{ url: "https://api.acme.example" }],
  });
}
 
// src/main.ts
import express from "express";
import swaggerUi from "swagger-ui-express";
import { generateOpenApiDocument } from "./openapi/document";
 
const app = express();
const spec = generateOpenApiDocument();
 
if (process.env.NODE_ENV !== "production") {
  app.use("/docs", swaggerUi.serve, swaggerUi.setup(spec));
}
app.get("/openapi.json", (_req, res) => res.json(spec));

1. PR updates openapi/v1.yaml
2. Reviewers comment on contract
3. Implement handlers + contract tests
4. CI: spectral lint + breaking-change diff (oasdiff)

// Share types with frontend via generated client - not raw OpenAPI dump
import type { components } from "./generated/api";
type Order = components["schemas"]["Order"];