OpenAPI Integration

Type-safe API communication between a Next.js backend and a Swift iOS client via OpenAPI 3.0.

Architecture

Backend (Next.js)                              iOS Client (Swift)
┌──────────────┐   ┌──────────────┐           ┌───────────────────────┐
│ Zod Schemas  │──▶│next-openapi  │──▶ JSON ──▶│swift-openapi-generator│
│              │   │   -gen       │           │ (SPM build plugin)    │
└──────────────┘   └──────────────┘           └───────────┬───────────┘
                                                          ▼
┌──────────────┐                              Types.swift + Client.swift
│ API Routes   │◀── JSDoc @openapi tags               (generated)
│ (app/api/v1) │                                          ▼
└──────────────┘                              Service Layer (manual)

Placeholders

All scripts accept these as arguments — replace with project-specific values:

Workflow

Initial setup

1. •Install next-openapi-gen in backend: ./scripts/admin-install-openapi.sh <backend-dir>
2. •Add "openapi:generate": "next-openapi-gen generate" to <backend-dir>/package.json scripts
3. •Create Zod schemas in <backend-dir>/lib/schemas/ → See backend-setup.md
4. •Annotate API routes with JSDoc @openapi tags → See jsdoc-reference.md
5. •Create the /api/openapi serving route → See backend-setup.md
6. •Set up Swift package dependencies and generator config → See ios-setup.md
7. •Create API client, auth middleware, and service layer → See ios-setup.md

After API changes (ongoing workflow)

1. •Edit routes in <backend-dir>/app/api/v1/ or schemas in <backend-dir>/lib/schemas/
2. •Start server: bun run dev in backend directory
3. •Regenerate and sync spec: ./scripts/ios-update-openapi.sh <backend-dir> <ios-app> <package-name>
4. •Build iOS package: ./scripts/ios-build-package.sh <ios-app> <package-name>
5. •Update Swift service layer to use new/changed generated types

Scripts

Override the server endpoint via env var: OPENAPI_DOCUMENTATION_ENDPOINT=https://api.example.com/api/openapi

References

• •Backend setup (Zod schemas, route annotations, spec serving): backend-setup.md
• •iOS setup (Package.swift, API client, middleware, services): ios-setup.md
• •JSDoc tag reference (all annotation tags for next-openapi-gen): jsdoc-reference.md
• •Troubleshooting (common issues and fixes): troubleshooting.md

Packages