From 9092ce8f93ac01d112f634bc11ac03c7d8e30846 Mon Sep 17 00:00:00 2001 From: hskwon Date: Thu, 6 Nov 2025 20:54:23 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Swagger=20=EB=AC=B8=EC=84=9C=20Phase=20?= =?UTF-8?q?1=20=EA=B0=9C=EC=84=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SAMInfo.php Auth 태그 상세화 - 인증 흐름 설명 추가 (API Key + Bearer Token) - 사용 예시 코드 추가 - IP 기반 접근 제어 안내 추가 - RegisterApi.php 보안 어노테이션 추가 - security={"ApiKeyAuth": {}} 설정 - "Authentication: Not Required" 오류 해결 - SWAGGER_AUDIT.md 작업 추적 문서 생성 - Phase별 점검 계획 수립 - 표준 체크리스트 정의 - 진행 상황 추적 체계 구축 --- app/Swagger/v1/RegisterApi.php | 1 + app/Swagger/v1/SAMInfo.php | 20 +++- claudedocs/SWAGGER_AUDIT.md | 177 +++++++++++++++++++++++++++++++++ 3 files changed, 197 insertions(+), 1 deletion(-) create mode 100644 claudedocs/SWAGGER_AUDIT.md diff --git a/app/Swagger/v1/RegisterApi.php b/app/Swagger/v1/RegisterApi.php index 807d880..f809a90 100644 --- a/app/Swagger/v1/RegisterApi.php +++ b/app/Swagger/v1/RegisterApi.php @@ -9,6 +9,7 @@ * summary="회원가입 및 테넌트 생성", * description="신규 회원가입과 동시에 새로운 테넌트(회사)를 생성합니다. 사용자는 자동으로 system_manager 역할이 부여되며 모든 테넌트 메뉴 권한을 갖습니다.", * operationId="register", + * security={{"ApiKeyAuth": {}}}, * * @OA\RequestBody( * required=true, diff --git a/app/Swagger/v1/SAMInfo.php b/app/Swagger/v1/SAMInfo.php index e28936e..31df575 100644 --- a/app/Swagger/v1/SAMInfo.php +++ b/app/Swagger/v1/SAMInfo.php @@ -33,7 +33,25 @@ * * @OA\Tag( * name="Auth", - * description="로그인/로그아웃 및 인증 관련 API" + * description="로그인/로그아웃 및 인증 관련 API + * + * **인증 흐름 (Authentication Flow)** + * 1. 모든 API 요청은 반드시 X-API-KEY 헤더가 필요합니다 (API Key 인증) + * 2. 사용자 인증이 필요한 API는 추가로 Bearer 토큰이 필요합니다 (JWT 인증) + * + * **API Key 사용 예시:** + * ``` + * X-API-KEY: your-api-key-here + * ``` + * + * **Bearer Token 사용 예시:** + * ``` + * Authorization: Bearer 1|abc123xyz456 + * ``` + * + * **IP 기반 접근:** + * - API Key가 없는 경우, IP 주소로 접근 제어가 가능합니다 + * - 단, 운영 환경에서는 반드시 API Key 사용을 권장합니다" * ) * @OA\Tag( * name="API Key 인증", diff --git a/claudedocs/SWAGGER_AUDIT.md b/claudedocs/SWAGGER_AUDIT.md new file mode 100644 index 0000000..a208722 --- /dev/null +++ b/claudedocs/SWAGGER_AUDIT.md @@ -0,0 +1,177 @@ +# SAM API Swagger 문서 점검 현황 + +## 📋 점검 개요 + +**목적:** SAM API의 Swagger 문서 품질을 체계적으로 점검하고 개선 +**범위:** 총 30개 Swagger API 파일 (app/Swagger/v1/) +**진행 방식:** Phase별 순차 점검 (세션 독립적) + +## 🎯 Phase 구성 + +### Phase 1: 기본 설정 및 보안 (완료 ✅) +**완료일:** 2025-11-06 + +#### 수정 내용: +1. ✅ **SAMInfo.php - Auth 태그 개선** + - 상세한 인증 흐름 설명 추가 + - API Key 및 Bearer Token 사용 예시 추가 + - IP 기반 접근 제어 안내 추가 + +2. ✅ **RegisterApi.php - 보안 어노테이션 추가** + - `security={{"ApiKeyAuth": {}}}` 추가 + - "Authentication: Not Required" 오류 해결 + +3. ℹ️ **서버 URL 설정** + - .env 파일의 L5_SWAGGER_CONST_HOST 변수로 관리 + - 사용자가 직접 수정 예정 (http://api.sam.kr/ → https://api.codebridge-x.com) + +### Phase 2: Auth API 상세 점검 (예정) +**대상 파일:** AuthApi.php +**점검 항목:** +- [ ] login API 요청/응답 스키마와 실제 값 일치성 +- [ ] logout API 요청/응답 검증 +- [ ] signup API 검증 (AuthApi와 RegisterApi 중복 확인) +- [ ] debug-apikey API 검증 +- [ ] 각 엔드포인트별 예시 값 추가 + +### Phase 3: 리소스별 순차 점검 (예정) +**총 30개 파일 중 28개 남음** + +**우선순위 높음 (핵심 기능):** +- [ ] ProductApi.php +- [ ] MaterialApi.php +- [ ] ClientApi.php +- [ ] UserApi.php +- [ ] TenantApi.php +- [ ] CategoryApi.php + +**우선순위 중간 (관리 기능):** +- [ ] RoleApi.php +- [ ] PermissionApi.php +- [ ] DepartmentApi.php +- [ ] MenuApi.php +- [ ] FieldProfileApi.php +- [ ] FileApi.php + +**우선순위 낮음 (부가 기능):** +- [ ] ModelApi.php +- [ ] BomCalculationApi.php +- [ ] PricingApi.php +- [ ] ClassificationApi.php +- [ ] AuditLogApi.php +- [ ] CommonApi.php + +**스키마 정의 파일:** +- [ ] CommonComponents.php +- [ ] ProductExtraSchemas.php +- [ ] CategoryExtras.php +- [ ] DesignBomTemplateExtras.php + +## 📝 표준 점검 체크리스트 + +각 API 파일 점검 시 다음 항목을 확인합니다: + +### 보안 및 인증 +- [ ] security 어노테이션 정확성 (ApiKeyAuth, BearerAuth) +- [ ] 인증 불필요 API의 명시적 표시 (security={}) + +### 요청 스키마 +- [ ] RequestBody 정의 완성도 +- [ ] required 필드 정확성 +- [ ] 타입 및 format 정확성 +- [ ] example 값의 실제 동작 일치성 +- [ ] nullable 속성 정확성 + +### 응답 스키마 +- [ ] Response 정의 완성도 (200, 400, 401, 403, 404, 422, 500) +- [ ] 성공 응답의 data 구조 정확성 +- [ ] 에러 응답의 message/errors 구조 일치성 +- [ ] example 값과 실제 응답 일치성 +- [ ] nullable/oneOf 구분 정확성 + +### 문서 품질 +- [ ] summary 명확성 +- [ ] description 상세성 +- [ ] 파라미터 설명 충실도 +- [ ] 예시 값의 실용성 +- [ ] tags 분류 적절성 + +### 스키마 재사용 +- [ ] 중복 스키마 존재 여부 +- [ ] 공통 스키마 활용 여부 +- [ ] ref 참조 정확성 + +## 🐛 발견된 이슈 + +### 해결됨 (✅) +1. **RegisterApi.php - 인증 필수 미표시** + - 문제: "Authentication: Not Required"로 표시됨 + - 원인: security 어노테이션 누락 + - 해결: `security={{"ApiKeyAuth": {}}}` 추가 + - 완료일: 2025-11-06 + +2. **SAMInfo.php - Auth 태그 설명 부족** + - 문제: 인증 흐름 및 사용 예시 부족 + - 해결: 상세한 설명 및 예시 추가 + - 완료일: 2025-11-06 + +### 진행 중 (🔄) +없음 + +### 대기 중 (⏳) +1. **서버 URL 변경** + - 현재: http://api.sam.kr/ + - 목표: https://api.codebridge-x.com + - 방법: .env 파일의 L5_SWAGGER_CONST_HOST 수정 + - 담당: 사용자 직접 수정 + +## 📊 진행 상황 + +### 전체 진도 +- **Phase 1:** ✅ 완료 (3/3) +- **Phase 2:** ⏳ 대기 중 (0/4) +- **Phase 3:** ⏳ 대기 중 (0/28) + +### 파일별 상태 +| 파일명 | 상태 | 점검일 | 비고 | +|--------|------|--------|------| +| SAMInfo.php | ✅ 완료 | 2025-11-06 | Auth 태그 개선 | +| RegisterApi.php | ✅ 완료 | 2025-11-06 | 보안 어노테이션 추가 | +| AuthApi.php | ⏳ 대기 | - | Phase 2 | +| ProductApi.php | ⏳ 대기 | - | Phase 3 (우선순위 높음) | +| MaterialApi.php | ⏳ 대기 | - | Phase 3 (우선순위 높음) | +| ... | ... | ... | ... | + +## 🔄 다음 단계 + +### 즉시 실행 가능 +1. Phase 1 변경사항 검증 + - Swagger 재생성: `php artisan l5-swagger:generate` + - Swagger UI에서 Auth 태그 및 Register API 확인 + - 실제 API 호출 테스트 + +2. Phase 2 시작 준비 + - AuthApi.php 파일 분석 + - 실제 Controller 및 Service 코드 확인 + - 요청/응답 검증 계획 수립 + +### 사용자 조치 필요 +- .env 파일의 L5_SWAGGER_CONST_HOST 수정 (운영 도메인 반영) + +## 📌 참고 사항 + +### 세션 독립성 유지 방법 +- 이 문서를 통해 작업 진행 상황 추적 +- Phase별 독립 실행 가능 +- 각 Phase 완료 후 Git 커밋으로 체크포인트 생성 + +### 품질 기준 +- SAM API Development Rules 준수 +- 실제 Controller/Service 코드와 100% 일치 +- 사용자가 직접 테스트 가능한 예시 값 +- i18n 메시지 키 사용 확인 + +### 관련 문서 +- `CLAUDE.md` - SAM 프로젝트 전체 가이드 +- `SAM API Development Rules` - API 개발 규칙 +- `l5-swagger` 문서 - Swagger 어노테이션 가이드 \ No newline at end of file