sync-openapi

Sync OpenAPI Specification

Verify and synchronize the OpenAPI specification (public/openapi.json) against the actual API route handlers in the tour-expense-tracker project.

4-Step Process

Step 1: Scan All API Routes

Find all route handlers:

src/app/api/**/route.ts

Exclude these directories from the public API spec:

• src/app/api/cron/* — internal cron job endpoints
• src/app/api/webhooks/* — webhook receivers (Stripe, etc.)
• src/app/api/auth/* — NextAuth internal routes
• src/app/api/health/* — health check endpoints

For each included route file, extract:

• HTTP methods: Which exports exist (GET, POST, PUT, PATCH, DELETE)
• Path: Derive the API path from the file system path (e.g., src/app/api/tours/[id]/route.ts becomes /api/tours/{id})
• Zod schemas: Find the request body validation schema and extract field names, types, and constraints
• Response shape: Identify the NextResponse.json() return structure
• Auth requirements: Which auth function is called (verifyGuideToken, getServerSession, verifyCronSecret, etc.)

Step 2: Extract Route Details

For each route, build a structured record:

Route: /api/tours/{id}
Methods: GET, PUT, DELETE
Auth: getServerSession (NextAuth)
Request body (PUT):
  - name: z.string().min(1)
  - startDate: z.string().datetime()
  - endDate: z.string().datetime()
  - status: z.enum(["draft", "active", "completed"])
Response (GET): { tour: Tour }
Response (PUT): { tour: Tour }
Response (DELETE): { success: boolean }

Step 3: Compare Against OpenAPI Spec

Read public/openapi.json and compare:

Symbol	Meaning
+	Missing: Route exists in code but not in spec
-	Removed: Route exists in spec but not in code
~	Mismatched: Route exists in both but details differ

Report each discrepancy:

## OpenAPI Sync Report

### Missing from spec (+)
+ POST /api/expenses — creates a new expense (added in recent commit)
+ GET  /api/reports/summary — returns financial summary

### Removed from code (-)
- GET  /api/legacy/tours — route file deleted, still in spec

### Mismatched (~)
~ PUT /api/tours/{id}
  - Spec says body.status: enum ["draft", "active"]
  - Code says body.status: enum ["draft", "active", "completed", "cancelled"]
~ GET /api/expenses
  - Spec missing query param: ?currency=string
  - Spec response missing field: expenses[].localAmount

Step 4: Apply Fixes (with --fix flag)

When invoked with --fix, update public/openapi.json:

• Add missing routes with paths, methods, request/response schemas, and auth requirements
• Remove routes that no longer exist in code
• Update mismatched schemas, parameters, and response shapes
• Preserve existing human-written descriptions and examples — do not overwrite them
• Preserve the info, servers, and security sections unless they reference removed auth schemes

After applying fixes, output the same sync report with a summary of changes made.

Conventions

• Path parameters use {param} notation (OpenAPI standard), not [param] (Next.js convention)
• Convert Next.js dynamic segments: [id] becomes {id}, [...slug] becomes a note in description
• Auth requirements map to OpenAPI security schemes:
  • getServerSession → bearerAuth or cookieAuth
  • verifyGuideToken / verifyDriverToken → bearerAuth with JWT
  • verifyCronSecret → apiKeyAuth in header
• Zod schemas map to JSON Schema in the spec's components/schemas section
• All monetary fields should be documented as type: string, format: decimal (since Decimal.js values are serialized as strings)

Output Example

## OpenAPI Sync Report

Scanned: 24 route files
Endpoints in code: 38
Endpoints in spec: 35

+3 missing | -0 removed | ~2 mismatched

### Missing (+)
+ POST /api/expenses
+ GET  /api/reports/summary
+ GET  /api/tours/{id}/participants

### Mismatched (~)
~ PUT  /api/tours/{id} — status enum outdated
~ GET  /api/expenses — missing query param and response field

Run with --fix to update public/openapi.json.