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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Post", description="게시글 관리")
 *
 * @OA\Schema(
 *   schema="Post",
 *   type="object",
 *   required={"id","board_id","title"},
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="board_id", type="integer", example=1),
 *   @OA\Property(property="user_id", type="integer", example=1, description="작성자 ID"),
 *   @OA\Property(property="title", type="string", example="공지사항 제목", description="제목"),
 *   @OA\Property(property="content", type="string", example="공지사항 내용입니다.", description="내용"),
 *   @OA\Property(property="editor_type", type="string", enum={"wysiwyg","markdown","text"}, example="wysiwyg"),
 *   @OA\Property(property="ip_address", type="string", nullable=true, example="127.0.0.1"),
 *   @OA\Property(property="is_notice", type="boolean", example=false, description="공지 여부"),
 *   @OA\Property(property="is_secret", type="boolean", example=false, description="비밀글 여부"),
 *   @OA\Property(property="views", type="integer", example=0, description="조회수"),
 *   @OA\Property(property="status", type="string", enum={"draft","published","hidden"}, example="published"),
 *   @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\Property(property="board", ref="#/components/schemas/Board"),
 *   @OA\Property(property="files", type="array", @OA\Items(type="object"))
 * )
 *
 * @OA\Schema(
 *   schema="PostPagination",
 *   type="object",
 *
 *   @OA\Property(property="current_page", type="integer", example=1),
 *   @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Post")),
 *   @OA\Property(property="first_page_url", type="string"),
 *   @OA\Property(property="from", type="integer", example=1),
 *   @OA\Property(property="last_page", type="integer", example=3),
 *   @OA\Property(property="last_page_url", type="string"),
 *   @OA\Property(property="next_page_url", type="string", nullable=true),
 *   @OA\Property(property="path", type="string"),
 *   @OA\Property(property="per_page", type="integer", example=15),
 *   @OA\Property(property="prev_page_url", type="string", nullable=true),
 *   @OA\Property(property="to", type="integer", example=15),
 *   @OA\Property(property="total", type="integer", example=50)
 * )
 *
 * @OA\Schema(
 *   schema="PostCreateRequest",
 *   type="object",
 *   required={"title","content"},
 *
 *   @OA\Property(property="title", type="string", maxLength=200, example="게시글 제목"),
 *   @OA\Property(property="content", type="string", example="게시글 내용입니다."),
 *   @OA\Property(property="editor_type", type="string", enum={"wysiwyg","markdown","text"}, example="wysiwyg"),
 *   @OA\Property(property="is_notice", type="boolean", example=false),
 *   @OA\Property(property="is_secret", type="boolean", example=false),
 *   @OA\Property(property="status", type="string", enum={"draft","published","hidden"}, example="published"),
 *   @OA\Property(property="custom_fields", type="object", nullable=true, description="커스텀 필드 값 (field_id: value)")
 * )
 *
 * @OA\Schema(
 *   schema="PostUpdateRequest",
 *   type="object",
 *
 *   @OA\Property(property="title", type="string", maxLength=200),
 *   @OA\Property(property="content", type="string"),
 *   @OA\Property(property="editor_type", type="string", enum={"wysiwyg","markdown","text"}),
 *   @OA\Property(property="is_notice", type="boolean"),
 *   @OA\Property(property="is_secret", type="boolean"),
 *   @OA\Property(property="status", type="string", enum={"draft","published","hidden"}),
 *   @OA\Property(property="custom_fields", type="object", nullable=true)
 * )
 *
 * @OA\Schema(
 *   schema="Comment",
 *   type="object",
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="post_id", type="integer", example=1),
 *   @OA\Property(property="user_id", type="integer", example=1),
 *   @OA\Property(property="parent_id", type="integer", nullable=true, description="부모 댓글 ID (대댓글인 경우)"),
 *   @OA\Property(property="content", type="string", example="댓글 내용"),
 *   @OA\Property(property="status", type="string", enum={"active","deleted"}, example="active"),
 *   @OA\Property(property="created_at", type="string", example="2025-01-01 12:00:00"),
 *   @OA\Property(property="replies", type="array", @OA\Items(ref="#/components/schemas/Comment"))
 * )
 *
 * @OA\Schema(
 *   schema="CommentCreateRequest",
 *   type="object",
 *   required={"content"},
 *
 *   @OA\Property(property="content", type="string", maxLength=2000, example="댓글 내용"),
 *   @OA\Property(property="parent_id", type="integer", nullable=true, description="대댓글인 경우 부모 댓글 ID")
 * )
 */
class PostApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/posts/my",
     *   tags={"Post"},
     *   summary="나의 게시글 목록",
     *   description="로그인한 사용자가 작성한 모든 게시글을 조회합니다.",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="board_code", in="query", description="게시판 코드 필터", @OA\Schema(type="string")),
     *   @OA\Parameter(name="search", in="query", description="제목/내용 검색", @OA\Schema(type="string")),
     *   @OA\Parameter(name="status", in="query", description="상태 필터", @OA\Schema(type="string", enum={"draft","published","hidden"})),
     *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="per_page", in="query", @OA\Schema(type="integer", example=15)),
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PostPagination"))
     *     })
     *   ),
     *
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function myPosts() {}

    /**
     * @OA\Get(
     *   path="/api/v1/boards/{code}/posts",
     *   tags={"Post"},
     *   summary="게시글 목록",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="per_page", in="query", @OA\Schema(type="integer", example=15)),
     *   @OA\Parameter(name="search", in="query", description="제목/내용 검색", @OA\Schema(type="string")),
     *   @OA\Parameter(name="is_notice", in="query", @OA\Schema(type="boolean")),
     *   @OA\Parameter(name="status", in="query", @OA\Schema(type="string", enum={"draft","published","hidden"})),
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PostPagination"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="게시판 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

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

    /**
     * @OA\Post(
     *   path="/api/v1/boards/{code}/posts",
     *   tags={"Post"},
     *   summary="게시글 작성",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/PostCreateRequest")),
     *
     *   @OA\Response(response=200, description="작성 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Post"))
     *     })
     *   ),
     *
     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=404, description="게시판 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Put(
     *   path="/api/v1/boards/{code}/posts/{id}",
     *   tags={"Post"},
     *   summary="게시글 수정",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/PostUpdateRequest")),
     *
     *   @OA\Response(response=200, description="수정 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Post"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="게시글 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/boards/{code}/posts/{id}",
     *   tags={"Post"},
     *   summary="게시글 삭제",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *   @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}/posts/{postId}/comments",
     *   tags={"Post"},
     *   summary="댓글 목록",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *   @OA\Parameter(name="postId", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @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/Comment")))
     *     })
     *   )
     * )
     */
    public function comments() {}

    /**
     * @OA\Post(
     *   path="/api/v1/boards/{code}/posts/{postId}/comments",
     *   tags={"Post"},
     *   summary="댓글 작성",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *   @OA\Parameter(name="postId", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/CommentCreateRequest")),
     *
     *   @OA\Response(response=200, description="작성 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Comment"))
     *     })
     *   ),
     *
     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function storeComment() {}

    /**
     * @OA\Put(
     *   path="/api/v1/boards/{code}/posts/{postId}/comments/{commentId}",
     *   tags={"Post"},
     *   summary="댓글 수정",
     *   description="본인이 작성한 댓글만 수정 가능",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *   @OA\Parameter(name="postId", in="path", required=true, @OA\Schema(type="integer")),
     *   @OA\Parameter(name="commentId", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/CommentCreateRequest")),
     *
     *   @OA\Response(response=200, description="수정 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Comment"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="댓글 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function updateComment() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/boards/{code}/posts/{postId}/comments/{commentId}",
     *   tags={"Post"},
     *   summary="댓글 삭제",
     *   description="본인이 작성한 댓글만 삭제 가능 (상태가 deleted로 변경됨)",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="code", in="path", required=true, description="게시판 코드", @OA\Schema(type="string")),
     *   @OA\Parameter(name="postId", in="path", required=true, @OA\Schema(type="integer")),
     *   @OA\Parameter(name="commentId", 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 destroyComment() {}
}