Swagger to Zod for TypeScript

Swagger and OpenAPI inputs

Swagger 2.0 and OpenAPI 3.x describe similar API contracts with different document shapes. FrameworkKit accepts Swagger 2.0 style `definitions` and OpenAPI 3.x `components.schemas` so TypeScript teams can generate validators from both legacy and modern API specs.

Recommended workflow

Start with shared definitions, inspect the generated validators, then refine edge cases such as custom formats, nullable values, and oneOf/anyOf unions. Keep generated validators close to API clients, webhooks, queue consumers, or route handlers that receive unknown data.

• Generate from `definitions` when the source is Swagger 2.0.
• Generate from `components.schemas` when the source is OpenAPI 3.x.
• Use fixture tests before relying on generated schemas in production.

Swagger 2.0 example

Older Swagger files often keep reusable schemas under `definitions`. Generate validators from those definitions, then migrate the source contract toward OpenAPI components when possible.

{
  "swagger": "2.0",
  "definitions": {
    "User": {
      "type": "object",
      "required": ["id", "email"],
      "properties": { "id": { "type": "string" }, "email": { "type": "string" } }
    }
  }
}

TypeScript runtime boundary

Use generated Zod schemas where TypeScript cannot protect you: parsed JSON, fetch responses, queue messages, webhooks, and data entering server actions.

const result = WebhookEventSchema.safeParse(await request.json());

if (!result.success) {
  return Response.json(
    { error: "Invalid webhook payload", issues: result.error.issues },
    { status: 400 },
  );
}

Refinement pass

Swagger contracts may describe broad strings where the application expects IDs, dates, URLs, or enum values. Add Zod refinements after generation when the business rule is stricter than the contract.

Swagger 2.0 required arrays

Swagger 2.0 keeps required property names in a `required` array on the object schema. During conversion, keys in that array should stay required while other properties become optional. This is separate from nullable handling, which is more explicit in OpenAPI 3.x.

• Check every object with a `required` array.
• Confirm optional generated fields match real response payloads.
• Do not assume a missing key and a `null` value mean the same thing.

References and circular models

Legacy Swagger definitions often reuse models through `$ref`. Keep referenced schemas named and reusable, then review circular or mutually recursive models before copying the result into application code.

{
  "definitions": {
    "Post": {
      "type": "object",
      "properties": {
        "author": { "$ref": "#/definitions/User" }
      }
    }
  }
}

FrameworkKit vs generated clients

Use FrameworkKit when the immediate job is to convert and review Zod validators in the browser. Use openapi-zod-client, Orval, Kubb, or another generator when the team wants a committed typed client that regenerates from the Swagger or OpenAPI document.

Migration checklist

Compare generated schemas against fixture payloads, then document whether Swagger or app code owns each validator so contract drift is visible.

• Keep generated type names stable across releases.
• Review local references and circular schema patterns.
• Add tests for nullable, missing, and malformed fields.
• Plan the migration from Swagger `definitions` to OpenAPI `components.schemas` if the API contract is still actively maintained.

Swagger to Zod migration map

Use FrameworkKit to generate the starter code, then review the output before shipping it in production.

OpenAPI to Zod resources

FAQ

Related comparisons

Related tools