SamProject/sam-api
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8df7f2cc09a1ef85362fe7486b340a30c828566b
sam-api/docs/SWAGGER_DOCUMENTATION_PLAN.md
kent 60ae7ab7bd docs: Swagger 미문서화 API 문서화 계획 추가 
- 29개 미문서화 엔드포인트 분류
- 우선순위별 작업 계획 (P1~P4)
- 예상 소요: 6일

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-21 14:35:29 +09:00

4.3 KiB
Raw Blame History

Swagger 미문서화 API 문서화 계획

생성일: 2024-12-21 총 29개 엔드포인트

참조 문서

문서 설명
공통 작업 프레임워크 세션 지속성, 작업 프로세스, TC 기반 검증
프로젝트 개발 정책 테이블 정책, 기술 스택, 코드 컨벤션

우선순위별 분류

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에서 검증