@famgia/omnify-laravel 0.0.108 → 0.0.109

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify-laravel",
-  "version": "0.0.108",
+  "version": "0.0.109",
   "description": "Laravel migration and TypeScript type generator for omnify-schema",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@famgia/omnify-types": "0.0.97",
-    "@famgia/omnify-core": "0.0.99",
-    "@famgia/omnify-atlas": "0.0.93"
+    "@famgia/omnify-types": "0.0.98",
+    "@famgia/omnify-core": "0.0.100",
+    "@famgia/omnify-atlas": "0.0.94"
   },
   "scripts": {
     "build": "tsup",

package/stubs/ai-guides/cursor/laravel-controller.mdc.stub

@@ -6,18 +6,34 @@ alwaysApply: false
 
 # Controller Rules
 
-## ⚠️ CRITICAL: OpenAPI Route Prefix
+## ⚠️ CRITICAL: Check Route Prefix BEFORE Writing OpenAPI
 
-**NEVER include `/api` in OpenAPI paths!** Laravel's `api.php` already has this prefix.
+**MUST check route file prefix first!** Don't assume - VERIFY.
+
+### Before Writing OpenAPI Path:
+
+1. **Check route file** → Which file has your route? (`api.php`, `web.php`, custom?)
+2. **Check prefix** → Look in `RouteServiceProvider` or `bootstrap/app.php`
+3. **Write path WITHOUT prefix** → OpenAPI path = Route definition path
 
 ```php
-// ❌ CRITICAL BUG - Results in /api/api/users !!
+// Route trong api.php (prefix: /api)
+Route::get('/users', [UserController::class, 'index']);
+
+// ❌ SAI - Duplicate prefix → /api/api/users !!
 #[OA\Get(path: '/api/users')]
 
-// ✅ CORRECT - api.php already adds /api prefix
-#[OA\Get(path: '/users')]
+// ✅ ĐÚNG - Path không có prefix
+#[OA\Get(path: '/users')]  // → /api/users
 ```
 
+| Route File | Prefix | Route Definition | OpenAPI Path |
+|------------|--------|------------------|--------------|
+| `api.php` | `/api` | `/users` | `/users` |
+| `web.php` | (none) | `/dashboard` | `/dashboard` |
+
+**Full guide:** `.claude/guides/laravel/openapi.md`
+
 ---
 
 ## Golden Rule: Thin Controller

package/stubs/ai-guides/laravel/openapi.md.stub

@@ -2,27 +2,70 @@
 
 > **Related:** [README](./README.md) | [Controller Guide](./controller-guide.md) | [Checklist](./checklist.md)
 
-## ⚠️ CRITICAL: Route Prefix Warning
+## ⚠️ CRITICAL: Check Route Prefix BEFORE Writing OpenAPI Path
 
-**DO NOT duplicate the `/api` prefix in OpenAPI paths!**
+### Step 1: Check Which Route File the Controller Uses
 
-Laravel's `routes/api.php` already has `/api` prefix applied automatically. If you write `/api/users` in OpenAPI, it becomes `/api/api/users` - a serious bug!
+```bash
+# Find where your route is registered
+grep -r "UserController" routes/
+```
+
+### Step 2: Check the Route Prefix in That File
+
+```php
+// bootstrap/app.php hoặc app/Providers/RouteServiceProvider.php
+// Tìm xem route file có prefix gì
+
+// Ví dụ Laravel 11+: bootstrap/app.php
+->withRouting(
+    api: __DIR__.'/../routes/api.php',    // ← /api prefix tự động!
+    web: __DIR__.'/../routes/web.php',
+    apiPrefix: 'api',                      // ← Đây là prefix!
+)
+
+// Ví dụ Laravel 10: app/Providers/RouteServiceProvider.php
+Route::middleware('api')
+    ->prefix('api')                        // ← Đây là prefix!
+    ->group(base_path('routes/api.php'));
+```
+
+### Step 3: Write OpenAPI Path = Actual Route Path (KHÔNG có prefix)
+
+| Route File | Route Definition | Prefix | OpenAPI Path | Final URL |
+|------------|------------------|--------|--------------|-----------|
+| `api.php` | `Route::get('/users', ...)` | `/api` | `path: '/users'` | `/api/users` |
+| `api.php` | `Route::get('/users/{id}', ...)` | `/api` | `path: '/users/{id}'` | `/api/users/1` |
+| `web.php` | `Route::get('/dashboard', ...)` | (none) | `path: '/dashboard'` | `/dashboard` |
+| `admin.php` | `Route::get('/stats', ...)` | `/admin/api` | `path: '/stats'` | `/admin/api/stats` |
+
+### ❌ CRITICAL BUG - Duplicate Prefix
 
 ```php
-// ❌ CRITICAL BUG - NEVER DO THIS!
-#[OA\Get(path: '/api/users')]  // Results in: /api/api/users !!
+// Route trong api.php (đã có prefix /api)
+Route::get('/users', [UserController::class, 'index']);
 
-// ✅ CORRECT - Routes file already has /api prefix
-#[OA\Get(path: '/users')]  // Results in: /api/users
+// ❌ SAI - Viết thêm /api vào path
+#[OA\Get(path: '/api/users')]  // → /api/api/users !!
+
+// ✅ ĐÚNG - Chỉ viết path sau prefix
+#[OA\Get(path: '/users')]  // → /api/users ✓
 ```
 
-**Remember:** The `api.php` file is loaded under the `/api` prefix by Laravel's RouteServiceProvider. You only need to write the path AFTER `/api`.
+### Quick Reference: Common Prefixes
+
+| Route File | Default Prefix | OpenAPI Server URL |
+|------------|----------------|-------------------|
+| `api.php` | `/api` | `#[OA\Server(url: '/api')]` |
+| `web.php` | (none) | `#[OA\Server(url: '/')]` |
+| Custom | Check RouteServiceProvider | Match the prefix |
+
+### Checklist Before Writing OpenAPI
 
-| Routes File  | OpenAPI Path  | Actual URL     |
-|--------------|---------------|----------------|
-| `api.php`    | `/users`      | `/api/users`   |
-| `api.php`    | `/users/{id}` | `/api/users/1` |
-| `web.php`    | `/dashboard`  | `/dashboard`   |
+- [ ] Check route file (`api.php` / `web.php` / custom)
+- [ ] Check prefix in `RouteServiceProvider` or `bootstrap/app.php`
+- [ ] OpenAPI path = Route path (WITHOUT prefix)
+- [ ] `#[OA\Server(url: ...)]` matches the prefix
 
 ---