sam-api/app/Swagger/v1/BoardApi.php

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Board", description="게시판 관리")
 *
 * @OA\Schema(
 *   schema="Board",
 *   type="object",
 *   required={"id","board_code","name"},
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="tenant_id", type="integer", nullable=true, example=1, description="테넌트 ID (시스템 게시판은 null)"),
 *   @OA\Property(property="is_system", type="boolean", example=false, description="시스템 게시판 여부"),
 *   @OA\Property(property="board_type", type="string", nullable=true, example="notice", description="게시판 유형 (notice, qna, faq 등)"),
 *   @OA\Property(property="board_code", type="string", example="NOTICE", description="게시판 코드"),
 *   @OA\Property(property="name", type="string", example="공지사항", description="게시판명"),
 *   @OA\Property(property="description", type="string", nullable=true, example="전사 공지사항 게시판", description="설명"),
 *   @OA\Property(property="editor_type", type="string", enum={"wysiwyg","markdown","text"}, example="wysiwyg", description="에디터 타입"),
 *   @OA\Property(property="allow_files", type="boolean", example=true, description="파일 첨부 허용"),
 *   @OA\Property(property="max_file_count", type="integer", example=5, description="최대 파일 수"),
 *   @OA\Property(property="max_file_size", type="integer", example=20480, description="최대 파일 크기 (KB)"),
 *   @OA\Property(property="extra_settings", type="object", nullable=true, description="추가 설정"),
 *   @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부"),
 *   @OA\Property(property="created_at", type="string", example="2025-01-01 12:00:00"),
 *   @OA\Property(property="updated_at", type="string", example="2025-01-01 12:00:00")
 * )
 *
 * @OA\Schema(
 *   schema="BoardField",
 *   type="object",
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="board_id", type="integer", example=1),
 *   @OA\Property(property="field_key", type="string", example="category", description="필드 키"),
 *   @OA\Property(property="field_label", type="string", example="카테고리", description="필드 라벨"),
 *   @OA\Property(property="field_type", type="string", example="select", description="필드 타입"),
 *   @OA\Property(property="is_required", type="boolean", example=false),
 *   @OA\Property(property="sort_order", type="integer", example=1),
 *   @OA\Property(property="options", type="object", nullable=true)
 * )
 *
 * @OA\Schema(
 *   schema="BoardCreateRequest",
 *   type="object",
 *   required={"board_code","name"},
 *
 *   @OA\Property(property="board_code", type="string", maxLength=50, example="NOTICE"),
 *   @OA\Property(property="board_type", type="string", nullable=true, maxLength=50, example="notice"),
 *   @OA\Property(property="name", type="string", maxLength=100, example="공지사항"),
 *   @OA\Property(property="description", type="string", nullable=true, maxLength=500),
 *   @OA\Property(property="editor_type", type="string", enum={"wysiwyg","markdown","text"}, example="wysiwyg"),
 *   @OA\Property(property="allow_files", type="boolean", example=true),
 *   @OA\Property(property="max_file_count", type="integer", example=5),
 *   @OA\Property(property="max_file_size", type="integer", example=20480),
 *   @OA\Property(property="extra_settings", type="object", nullable=true),
 *   @OA\Property(property="is_active", type="boolean", example=true)
 * )
 *
 * @OA\Schema(
 *   schema="BoardUpdateRequest",
 *   type="object",
 *
 *   @OA\Property(property="board_code", type="string", maxLength=50),
 *   @OA\Property(property="board_type", type="string", nullable=true, maxLength=50),
 *   @OA\Property(property="name", type="string", maxLength=100),
 *   @OA\Property(property="description", type="string", nullable=true, maxLength=500),
 *   @OA\Property(property="editor_type", type="string", enum={"wysiwyg","markdown","text"}),
 *   @OA\Property(property="allow_files", type="boolean"),
 *   @OA\Property(property="max_file_count", type="integer"),
 *   @OA\Property(property="max_file_size", type="integer"),
 *   @OA\Property(property="extra_settings", type="object", nullable=true),
 *   @OA\Property(property="is_active", type="boolean")
 * )
 */
class BoardApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/boards",
     *   tags={"Board"},
     *   summary="접근 가능한 게시판 목록 (시스템 + 테넌트)",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="board_type", in="query", description="게시판 유형 필터", @OA\Schema(type="string")),
     *   @OA\Parameter(name="search", in="query", description="게시판명 검색", @OA\Schema(type="string")),
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Board")))
     *     })
     *   ),
     *
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *   path="/api/v1/boards/tenant",
     *   tags={"Board"},
     *   summary="테넌트 게시판 목록만 조회",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="board_type", in="query", @OA\Schema(type="string")),
     *   @OA\Parameter(name="search", in="query", @OA\Schema(type="string")),
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Board")))
     *     })
     *   )
     * )
     */
    public function tenantBoards() {}

    /**
     * @OA\Get(
     *   path="/api/v1/boards/{code}",
     *   tags={"Board"},
     *   summary="게시판 상세 조회 (코드 기반)",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Board"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="게시판 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *   path="/api/v1/boards",
     *   tags={"Board"},
     *   summary="테넌트 게시판 생성",
     *   description="현재 테넌트에 새 게시판을 생성합니다. 시스템 게시판은 mng에서만 생성 가능합니다.",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/BoardCreateRequest")),
     *
     *   @OA\Response(response=200, description="생성 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Board"))
     *     })
     *   ),
     *
     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Put(
     *   path="/api/v1/boards/{id}",
     *   tags={"Board"},
     *   summary="테넌트 게시판 수정",
     *   description="테넌트 게시판만 수정 가능. 시스템 게시판은 수정 불가.",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/BoardUpdateRequest")),
     *
     *   @OA\Response(response=200, description="수정 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Board"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="게시판 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/boards/{id}",
     *   tags={"Board"},
     *   summary="테넌트 게시판 삭제",
     *   description="테넌트 게시판만 삭제 가능. 시스템 게시판은 삭제 불가.",
     *   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/ApiResponse")),
     *   @OA\Response(response=404, description="게시판 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}

    /**
     * @OA\Get(
     *   path="/api/v1/boards/{code}/fields",
     *   tags={"Board"},
     *   summary="게시판 커스텀 필드 목록",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/BoardField")))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="게시판 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function fields() {}
}