SamProject/sam-api
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
92c60ff39fe90e14aa7cd60f07d59beb3d64feec
sam-api/app/Swagger/v1/AuthApi.php
hskwon 977207f2fa docs: Swagger 문서 Phase 2 완료 (Auth API 점검) 
- AuthApi.php 응답 형식 실제 코드와 일치화
  - logout: {success, message, data} → {message}
  - debug-apikey: description 및 응답 형식 추가

- login API 검증 완료
  - 요청/응답 스키마와 실제 코드 일치 확인
  - user, tenant, menus 구조 정확성 검증

- signup API 중복 확인
  - AuthApi.php와 RegisterApi.php 동일 엔드포인트
  - RegisterApi.php가 더 상세 (테넌트 생성 포함)

- SWAGGER_AUDIT.md 업데이트
  - Phase 2 완료 상태로 변경
  - 발견 이슈 4건 추가 (모두 해결)
2025-11-07 02:15:52 +09:00

247 lines
11 KiB
PHP
Raw Blame History

<?php
namespace App\Swagger\v1;
/**
* @OA\Tag(name="Auth", description="로그인/로그아웃/회원가입")
*/
/**
* 회원가입 요청/응답 스키마
* -----------------------------------------------------------------------------
* 필요 시 공용 components 영역으로 이동해도 됩니다.
*/
/**
* @OA\Schema(
* schema="SignupRequest",
* type="object",
* required={"user_id","name","email","password"},
*
* @OA\Property(property="user_id", type="string", maxLength=255, example="userId", description="로그인 ID (고유)"),
* @OA\Property(property="name", type="string", maxLength=255, example="Kent"),
* @OA\Property(property="email", type="string", maxLength=100, example="codebridge@gmail.com"),
* @OA\Property(property="phone", type="string", maxLength=30, nullable=true, example="010-4820-9104"),
* @OA\Property(property="password", type="string", minLength=8, maxLength=64, example="StrongPass!1234")
* )
*
* @OA\Schema(
* schema="SignupResponseData",
* type="object",
*
* @OA\Property(
* property="user",
* ref="#/components/schemas/Member"
* )
* )
*
* @OA\Schema(
* schema="MemberBrief",
* type="object",
* description="회원 요약 정보(회원가입 응답용)",
* required={"id","user_id","name","email","phone"},
*
* @OA\Property(property="id", type="integer", example=6),
* @OA\Property(property="user_id", type="string", example="userId"),
* @OA\Property(property="name", type="string", example="Kent"),
* @OA\Property(property="email", type="string", example="codebridge1@gmail.com"),
* @OA\Property(property="phone", type="string", example="010-4820-9104")
* )
*/
class AuthApi
{
/**
* @OA\Get(
* path="/api/v1/debug-apikey",
* tags={"Auth"},
* summary="API Key 인증 확인",
* description="API Key가 유효한지 확인합니다. Bearer 토큰은 선택사항입니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Response(
* response=200,
* description="API Key 인증 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="message", type="string", example="API Key 인증 성공")
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function debugApiKey() {}
/**
* @OA\Post(
* path="/api/v1/login",
* tags={"Auth"},
* summary="로그인 (토큰 + 사용자 정보 + 테넌트 + 메뉴)",
* description="로그인 성공 시 인증 토큰과 함께 사용자 정보, 활성 테넌트 정보, 접근 가능한 메뉴 목록을 반환합니다.",
* security={{"ApiKeyAuth": {}}},
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(
* required={"user_id","user_pwd"},
*
* @OA\Property(property="user_id", type="string", example="hamss"),
* @OA\Property(property="user_pwd", type="string", example="StrongPass!1234")
* )
* ),
*
* @OA\Response(
* response=200,
* description="로그인 성공",
*
* @OA\JsonContent(
* type="object",
*
* @OA\Property(property="message", type="string", example="로그인 성공"),
* @OA\Property(property="user_token", type="string", example="1|abc123xyz456"),
* @OA\Property(
* property="user",
* type="object",
* description="사용자 기본 정보",
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="user_id", type="string", example="hamss"),
* @OA\Property(property="name", type="string", example="홍길동"),
* @OA\Property(property="email", type="string", example="hamss@example.com"),
* @OA\Property(property="phone", type="string", nullable=true, example="010-1234-5678")
* ),
* @OA\Property(
* property="tenant",
* type="object",
* nullable=true,
* description="활성 테넌트 정보 (is_default=1 우선, 없으면 is_active=1 중 첫 번째, 없으면 null)",
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="company_name", type="string", example="주식회사 코드브리지"),
* @OA\Property(property="business_num", type="string", nullable=true, example="123-45-67890"),
* @OA\Property(property="tenant_st_code", type="string", nullable=true, example="ACTIVE"),
* @OA\Property(
* property="other_tenants",
* type="array",
* description="사용자가 소속된 다른 활성 테넌트 목록",
*
* @OA\Items(
* type="object",
*
* @OA\Property(property="tenant_id", type="integer", example=2),
* @OA\Property(property="company_name", type="string", example="주식회사 샘플"),
* @OA\Property(property="business_num", type="string", nullable=true, example="987-65-43210"),
* @OA\Property(property="tenant_st_code", type="string", nullable=true, example="ACTIVE")
* )
* )
* ),
* @OA\Property(
* property="menus",
* type="array",
* description="사용자가 접근 가능한 메뉴 목록 (menu:{menu_id}.view 권한 체크, override deny/allow 적용)",
*
* @OA\Items(
* type="object",
*
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
* @OA\Property(property="name", type="string", example="대시보드"),
* @OA\Property(property="url", type="string", nullable=true, example="/dashboard"),
* @OA\Property(property="icon", type="string", nullable=true, example="dashboard"),
* @OA\Property(property="sort_order", type="integer", example=1),
* @OA\Property(property="is_external", type="boolean", example=false, description="외부 링크 여부"),
* @OA\Property(property="external_url", type="string", nullable=true, example="https://example.com", description="외부 링크 URL")
* )
* )
* )
* ),
*
* @OA\Response(
* response="200 (테넌트 없음)",
* description="로그인 성공 - 활성 테넌트 없는 경우",
*
* @OA\JsonContent(
* type="object",
*
* @OA\Property(property="message", type="string", example="로그인 성공"),
* @OA\Property(property="user_token", type="string", example="1|abc123xyz456"),
* @OA\Property(
* property="user",
* type="object",
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="user_id", type="string", example="hamss"),
* @OA\Property(property="name", type="string", example="홍길동"),
* @OA\Property(property="email", type="string", example="hamss@example.com"),
* @OA\Property(property="phone", type="string", nullable=true, example="010-1234-5678")
* ),
* @OA\Property(property="tenant", type="null", example=null),
* @OA\Property(property="menus", type="array", @OA\Items())
* )
* ),
*
* @OA\Response(response=400, description="필수 파라미터 누락", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=401, description="로그인 실패 (비밀번호 불일치)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=404, description="사용자를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function login() {}
/**
* @OA\Post(
* path="/api/v1/logout",
* tags={"Auth"},
* summary="로그아웃 (Access 및 Token 무효화)",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Response(
* response=200,
* description="로그아웃 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="message", type="string", example="로그아웃 완료")
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function logout() {}
/**
* @OA\Post(
* path="/api/v1/signup",
* tags={"Auth"},
* summary="회원가입",
* description="신규 회원을 생성합니다. (API Key 필요)",
* security={{"ApiKeyAuth": {}}},
*
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/SignupRequest")),
*
* @OA\Response(
* response=200,
* description="회원가입 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(
* property="data",
* type="object",
* @OA\Property(property="user", ref="#/components/schemas/MemberBrief")
* )
* )
* }
* )
* ),
*
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=401, description="인증 실패(API Key 누락/오류)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function signup() {}
}
Reference in New Issue View Git Blame Copy Permalink