From 47728f9786619b81d28aeba46a1f5743b5c513b7 Mon Sep 17 00:00:00 2001 From: kent Date: Sun, 21 Dec 2025 14:55:24 +0900 Subject: [PATCH] =?UTF-8?q?chore:=20Swagger=20=EB=AC=B8=EC=84=9C=ED=99=94?= =?UTF-8?q?=20=EA=B3=84=ED=9A=8D=20=ED=8C=8C=EC=9D=BC=20=EC=82=AD=EC=A0=9C?= =?UTF-8?q?=20(=EC=9E=91=EC=97=85=20=EC=99=84=EB=A3=8C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/SWAGGER_DOCUMENTATION_PLAN.md | 89 ------------------------------ 1 file changed, 89 deletions(-) delete mode 100644 docs/SWAGGER_DOCUMENTATION_PLAN.md diff --git a/docs/SWAGGER_DOCUMENTATION_PLAN.md b/docs/SWAGGER_DOCUMENTATION_PLAN.md deleted file mode 100644 index 7e87591..0000000 --- a/docs/SWAGGER_DOCUMENTATION_PLAN.md +++ /dev/null @@ -1,89 +0,0 @@ -# Swagger ๋ฏธ๋ฌธ์„œํ™” API ๋ฌธ์„œํ™” ๊ณ„ํš - -> ์ƒ์„ฑ์ผ: 2024-12-21 -> ์ด 29๊ฐœ ์—”๋“œํฌ์ธํŠธ - -## ์ฐธ์กฐ ๋ฌธ์„œ - -| ๋ฌธ์„œ | ์„ค๋ช… | -|------|------| -| [๊ณตํ†ต ์ž‘์—… ํ”„๋ ˆ์ž„์›Œํฌ](../../docs/guides/common-workflow-framework.md) | ์„ธ์…˜ ์ง€์†์„ฑ, ์ž‘์—… ํ”„๋กœ์„ธ์Šค, TC ๊ธฐ๋ฐ˜ ๊ฒ€์ฆ | -| [ํ”„๋กœ์ ํŠธ ๊ฐœ๋ฐœ ์ •์ฑ…](../../docs/guides/PROJECT_DEVELOPMENT_POLICY.md) | ํ…Œ์ด๋ธ” ์ •์ฑ…, ๊ธฐ์ˆ  ์Šคํƒ, ์ฝ”๋“œ ์ปจ๋ฒค์…˜ | - -## ์šฐ์„ ์ˆœ์œ„๋ณ„ ๋ถ„๋ฅ˜ - -### P1: ํ•ต์‹ฌ ๊ธฐ๋Šฅ (์ฆ‰์‹œ) -| ์—”๋“œํฌ์ธํŠธ | ๋ฉ”์„œ๋“œ | ์„ค๋ช… | ๋Œ€์ƒ ํŒŒ์ผ | -|-----------|--------|------|----------| -| `/api/v1/token-login` | POST | ํ† ํฐ ๋กœ๊ทธ์ธ | `AuthApi.php` | -| `/api/v1/departments/tree` | GET | ๋ถ€์„œ ํŠธ๋ฆฌ ์กฐํšŒ | `DepartmentApi.php` | - -### P2: Admin Global Menus (8๊ฐœ) -| ์—”๋“œํฌ์ธํŠธ | ๋ฉ”์„œ๋“œ | ์„ค๋ช… | ๋Œ€์ƒ ํŒŒ์ผ | -|-----------|--------|------|----------| -| `/api/v1/admin/global-menus` | GET | ์ „์—ญ ๋ฉ”๋‰ด ๋ชฉ๋ก | `AdminGlobalMenuApi.php` (์‹ ๊ทœ) | -| `/api/v1/admin/global-menus` | POST | ์ „์—ญ ๋ฉ”๋‰ด ์ƒ์„ฑ | `AdminGlobalMenuApi.php` | -| `/api/v1/admin/global-menus/stats` | GET | ์ „์—ญ ๋ฉ”๋‰ด ํ†ต๊ณ„ | `AdminGlobalMenuApi.php` | -| `/api/v1/admin/global-menus/tree` | GET | ์ „์—ญ ๋ฉ”๋‰ด ํŠธ๋ฆฌ | `AdminGlobalMenuApi.php` | -| `/api/v1/admin/global-menus/reorder` | POST | ์ „์—ญ ๋ฉ”๋‰ด ์ •๋ ฌ | `AdminGlobalMenuApi.php` | -| `/api/v1/admin/global-menus/{id}` | GET | ์ „์—ญ ๋ฉ”๋‰ด ์ƒ์„ธ | `AdminGlobalMenuApi.php` | -| `/api/v1/admin/global-menus/{id}` | PUT | ์ „์—ญ ๋ฉ”๋‰ด ์ˆ˜์ • | `AdminGlobalMenuApi.php` | -| `/api/v1/admin/global-menus/{id}` | DELETE | ์ „์—ญ ๋ฉ”๋‰ด ์‚ญ์ œ | `AdminGlobalMenuApi.php` | -| `/api/v1/admin/global-menus/{id}/sync-to-tenants` | POST | ํ…Œ๋„ŒํŠธ ๋™๊ธฐํ™” | `AdminGlobalMenuApi.php` | - -### P3: Model Sets (10๊ฐœ) -| ์—”๋“œํฌ์ธํŠธ | ๋ฉ”์„œ๋“œ | ์„ค๋ช… | ๋Œ€์ƒ ํŒŒ์ผ | -|-----------|--------|------|----------| -| `/api/v1/model-sets` | GET | ๋ชจ๋ธ์…‹ ๋ชฉ๋ก | `ModelSetApi.php` (์‹ ๊ทœ) | -| `/api/v1/model-sets` | POST | ๋ชจ๋ธ์…‹ ์ƒ์„ฑ | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}` | GET | ๋ชจ๋ธ์…‹ ์ƒ์„ธ | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}` | PUT | ๋ชจ๋ธ์…‹ ์ˆ˜์ • | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}` | DELETE | ๋ชจ๋ธ์…‹ ์‚ญ์ œ | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}/bom-templates` | GET | BOM ํ…œํ”Œ๋ฆฟ ์กฐํšŒ | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}/estimate-parameters` | GET | ๊ฒฌ์  ํŒŒ๋ผ๋ฏธํ„ฐ | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}/fields` | GET | ํ•„๋“œ ์กฐํšŒ | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}/calculate-bom` | POST | BOM ๊ณ„์‚ฐ | `ModelSetApi.php` | -| `/api/v1/model-sets/{id}/clone` | POST | ๋ชจ๋ธ์…‹ ๋ณต์ œ | `ModelSetApi.php` | - -### P4: Menus Sync (6๊ฐœ) -| ์—”๋“œํฌ์ธํŠธ | ๋ฉ”์„œ๋“œ | ์„ค๋ช… | ๋Œ€์ƒ ํŒŒ์ผ | -|-----------|--------|------|----------| -| `/api/v1/menus/available-global` | GET | ์‚ฌ์šฉ ๊ฐ€๋Šฅ ์ „์—ญ ๋ฉ”๋‰ด | `MenuApi.php` | -| `/api/v1/menus/sync-status` | GET | ๋™๊ธฐํ™” ์ƒํƒœ | `MenuApi.php` | -| `/api/v1/menus/trashed` | GET | ์‚ญ์ œ๋œ ๋ฉ”๋‰ด | `MenuApi.php` | -| `/api/v1/menus/sync` | POST | ๋ฉ”๋‰ด ๋™๊ธฐํ™” | `MenuApi.php` | -| `/api/v1/menus/sync-new` | POST | ์‹ ๊ทœ ๋ฉ”๋‰ด ๋™๊ธฐํ™” | `MenuApi.php` | -| `/api/v1/menus/sync-updates` | POST | ์—…๋ฐ์ดํŠธ ๋™๊ธฐํ™” | `MenuApi.php` | -| `/api/v1/menus/{id}/restore` | POST | ๋ฉ”๋‰ด ๋ณต์› | `MenuApi.php` | - -## ์ž‘์—… ๊ณ„ํš - -### Phase 1: P1 ํ•ต์‹ฌ (1์ผ) -- [ ] `AuthApi.php` - token-login ์ถ”๊ฐ€ -- [ ] `DepartmentApi.php` - departments/tree ์ถ”๊ฐ€ - -### Phase 2: Admin Global Menus (2์ผ) -- [ ] `AdminGlobalMenuApi.php` ์‹ ๊ทœ ์ƒ์„ฑ -- [ ] 9๊ฐœ ์—”๋“œํฌ์ธํŠธ ๋ฌธ์„œํ™” - -### Phase 3: Model Sets (2์ผ) -- [ ] `ModelSetApi.php` ์‹ ๊ทœ ์ƒ์„ฑ -- [ ] 10๊ฐœ ์—”๋“œํฌ์ธํŠธ ๋ฌธ์„œํ™” - -### Phase 4: Menus Sync (1์ผ) -- [ ] `MenuApi.php` ๊ธฐ์กด ํŒŒ์ผ์— 7๊ฐœ ์—”๋“œํฌ์ธํŠธ ์ถ”๊ฐ€ - -## ์˜ˆ์ƒ ์†Œ์š”: 6์ผ - -## ์ž‘์—… ๊ทœ์น™ - -### ์ฐธ์กฐ ๋ฌธ์„œ ์ค€์ˆ˜์‚ฌํ•ญ -- **๊ณตํ†ต ์ž‘์—… ํ”„๋ ˆ์ž„์›Œํฌ**: ์„ธ์…˜ ๊ฐ„ ์ง€์†์„ฑ ์œ ์ง€ (Serena ๋ฉ”๋ชจ๋ฆฌ ํ™œ์šฉ) -- **ํ”„๋กœ์ ํŠธ ๊ฐœ๋ฐœ ์ •์ฑ…**: ์ถ”์ธก ๊ธˆ์ง€ ์›์น™ - ์ปจํŠธ๋กค๋Ÿฌ/๋ผ์šฐํŠธ ์‹ค์ œ ํ™•์ธ ํ›„ ๋ฌธ์„œํ™” - -### Swagger ์ž‘์—… ์ ˆ์ฐจ -1. ๋ผ์šฐํŠธ ํŒŒ์ผ์—์„œ ์‹ค์ œ ๊ฒฝ๋กœ/ํŒŒ๋ผ๋ฏธํ„ฐ ํ™•์ธ -2. ์ปจํŠธ๋กค๋Ÿฌ์—์„œ Request/Response ๊ตฌ์กฐ ํ™•์ธ -3. ๊ธฐ์กด Swagger ํŒŒ์ผ ํŒจํ„ด ์ฐธ์กฐ (ApiResponse, ErrorResponse ๋“ฑ) -4. `php artisan l5-swagger:generate` ์‹คํ–‰ -5. Swagger UI์—์„œ ๊ฒ€์ฆ