From tour-dev-toolkit
This skill should be used when the user asks to "sync openapi", "update API docs", "check API spec", "verify openapi", "API documentation out of date", or needs to verify the OpenAPI specification matches actual routes.
npx claudepluginhub boburshoh122000/claude-plugins-bobur --plugin tour-dev-toolkitThis skill uses the workspace's default tool permissions.
Verify and synchronize the OpenAPI specification (`public/openapi.json`) against the actual API route handlers in the tour-expense-tracker project.
Verifies tests pass on completed feature branch, presents options to merge locally, create GitHub PR, keep as-is or discard; executes choice and cleans up worktree.
Guides root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Writes implementation plans from specs for multi-step tasks, mapping files and breaking into TDD bite-sized steps before coding.
Verify and synchronize the OpenAPI specification (public/openapi.json) against the actual API route handlers in the tour-expense-tracker project.
Find all route handlers:
src/app/api/**/route.ts
Exclude these directories from the public API spec:
src/app/api/cron/* — internal cron job endpointssrc/app/api/webhooks/* — webhook receivers (Stripe, etc.)src/app/api/auth/* — NextAuth internal routessrc/app/api/health/* — health check endpointsFor each included route file, extract:
GET, POST, PUT, PATCH, DELETE)src/app/api/tours/[id]/route.ts becomes /api/tours/{id})NextResponse.json() return structureverifyGuideToken, getServerSession, verifyCronSecret, etc.)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 }
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
--fix flag)When invoked with --fix, update public/openapi.json:
info, servers, and security sections unless they reference removed auth schemesAfter applying fixes, output the same sync report with a summary of changes made.
{param} notation (OpenAPI standard), not [param] (Next.js convention)[id] becomes {id}, [...slug] becomes a note in descriptiongetServerSession → bearerAuth or cookieAuthverifyGuideToken / verifyDriverToken → bearerAuth with JWTverifyCronSecret → apiKeyAuth in headercomponents/schemas sectiontype: string, format: decimal (since Decimal.js values are serialized as strings)## 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.