sam-docs/dev/guides/swagger-guide.md

Swagger 문서화 가이드

업데이트: 2025-12-26

---

개요

라이브러리: l5-swagger 9.0

Swagger 구조

파일 위치

• 경로: app/Swagger/v1/
• 파일명: {Resource}Api.php (예: CategoryApi.php, ClientApi.php, ProductApi.php)

원칙

• Controller Clean: Controllers contain ONLY business logic, NO Swagger annotations
• Separate Files: Swagger annotations are written in separate PHP class files

---

Swagger 파일 구조

기본 템플릿

<?php
namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Resource", description="리소스 관리")
 *
 * @OA\Schema(
 *     schema="Resource",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="name", type="string"),
 *     ...
 * )
 *
 * @OA\Schema(
 *     schema="ResourcePagination",
 *     allOf={
 *         @OA\Schema(ref="#/components/schemas/PaginationMeta"),
 *         @OA\Schema(
 *             @OA\Property(
 *                 property="data",
 *                 type="array",
 *                 @OA\Items(ref="#/components/schemas/Resource")
 *             )
 *         )
 *     }
 * )
 *
 * @OA\Schema(
 *     schema="ResourceCreateRequest",
 *     required={"name"},
 *     @OA\Property(property="name", type="string"),
 *     ...
 * )
 *
 * @OA\Schema(
 *     schema="ResourceUpdateRequest",
 *     @OA\Property(property="name", type="string"),
 *     ...
 * )
 */
class ResourceApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/resources",
     *     tags={"Resource"},
     *     summary="리소스 목록 조회",
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *     @OA\Parameter(
     *         name="page",
     *         in="query",
     *         @OA\Schema(type="integer", default=1)
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *         @OA\JsonContent(ref="#/components/schemas/ResourcePagination")
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Post(
     *     path="/api/v1/resources",
     *     tags={"Resource"},
     *     summary="리소스 생성",
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *     @OA\RequestBody(
     *         required=true,
     *         @OA\JsonContent(ref="#/components/schemas/ResourceCreateRequest")
     *     ),
     *     @OA\Response(
     *         response=201,
     *         description="생성 성공",
     *         @OA\JsonContent(ref="#/components/schemas/Resource")
     *     )
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *     path="/api/v1/resources/{id}",
     *     tags={"Resource"},
     *     summary="리소스 상세 조회",
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         @OA\Schema(type="integer")
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *         @OA\JsonContent(ref="#/components/schemas/Resource")
     *     )
     * )
     */
    public function show() {}

    /**
     * @OA\Put(
     *     path="/api/v1/resources/{id}",
     *     tags={"Resource"},
     *     summary="리소스 수정",
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         @OA\Schema(type="integer")
     *     ),
     *     @OA\RequestBody(
     *         required=true,
     *         @OA\JsonContent(ref="#/components/schemas/ResourceUpdateRequest")
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *         @OA\JsonContent(ref="#/components/schemas/Resource")
     *     )
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/resources/{id}",
     *     tags={"Resource"},
     *     summary="리소스 삭제",
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         @OA\Schema(type="integer")
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="삭제 성공"
     *     )
     * )
     */
    public function destroy() {}
}

---

필수 규칙

1. Tags

• Resource-based (User, Auth, Product, BOM, Client...)
• 리소스별 논리적 그룹핑

2. Security

security={{"ApiKeyAuth": {}, "BearerAuth": {}}}

• 모든 엔드포인트에 필수

3. Schemas

• Resource model: 응답 데이터 구조
• Pagination: 페이지네이션 응답 (PaginationMeta 재사용)
• CreateRequest: 생성 요청 스키마
• UpdateRequest: 수정 요청 스키마

4. Parameters

• Path/Query/Body parameters 명확히 정의
• 예시 값 제공 (example 속성)

5. 중복 방지

• No duplicate schemas: 공통 스키마는 재사용
• nullable/oneOf 정확한 구분

---

Swagger 재생성

php artisan l5-swagger:generate

실행 시점:

• Swagger 파일 생성/수정 후
• API 엔드포인트 변경 후

---

접근 방법

• Swagger UI: http://api.sam.kr/api-docs/index.html
• JSON Spec: http://api.sam.kr/docs/api-docs.json

---

체크리스트

✓ Swagger 파일 위치: app/Swagger/v1/{Resource}Api.php
✓ Controller에 Swagger 주석 없음
✓ Resource 태그 적용
✓ ApiKeyAuth + BearerAuth 스키마
✓ 스키마 재사용 (중복 없음)
✓ 예시 값 제공
✓ php artisan l5-swagger:generate 실행

관련 문서

• API 개발 규칙
• 개발 명령어

---

최종 업데이트: 2025-12-26