Gnuboard7/modules/_bundled/gnuboard7-hello_module/docs/api/memos.md

Memos API 레퍼런스

소유: module gnuboard7-hello_module · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.

---

TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Memos 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

---

GET /api/modules/gnuboard7-hello_module/admin/memos

• 라우트명: api.modules.gnuboard7-hello_module.admin.memos.index
• 컨트롤러: Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@index
• 인증/권한: auth:sanctum + permission:gnuboard7-hello_module.memos.read

요청 파라미터

이름	위치	타입	필수	허용값	용도
page	query	integer	아니오	min 1	조회할 페이지 번호 (1부터 시작)
per_page	query	integer	아니오	min 1, max 100	페이지당 항목 수

요청 예시

GET /api/modules/gnuboard7-hello_module/admin/memos?page=1&per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(gnuboard7-hello_module.memos.read)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

POST /api/modules/gnuboard7-hello_module/admin/memos

• 라우트명: api.modules.gnuboard7-hello_module.admin.memos.store
• 컨트롤러: Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@store
• 인증/권한: auth:sanctum + permission:gnuboard7-hello_module.memos.create

요청 파라미터

이름	위치	타입	필수	허용값	용도
title	body	string	예	max 255	제목
content	body	string	예	—	본문 내용

요청 예시

POST /api/modules/gnuboard7-hello_module/admin/memos HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "title": "예시 제목",
    "content": "예시 내용입니다."
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(gnuboard7-hello_module.memos.create)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

DELETE /api/modules/gnuboard7-hello_module/admin/memos/{id}

• 라우트명: api.modules.gnuboard7-hello_module.admin.memos.destroy
• 컨트롤러: Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@destroy
• 인증/권한: auth:sanctum + permission:gnuboard7-hello_module.memos.delete

요청 파라미터

이름	위치	타입	필수	허용값	용도
id	path	string	예	—	대상 리소스의 식별자

요청 예시

DELETE /api/modules/gnuboard7-hello_module/admin/memos/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(gnuboard7-hello_module.memos.delete)이 없는 경우
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

GET /api/modules/gnuboard7-hello_module/admin/memos/{id}

• 라우트명: api.modules.gnuboard7-hello_module.admin.memos.show
• 컨트롤러: Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@show
• 인증/권한: auth:sanctum + permission:gnuboard7-hello_module.memos.read

요청 파라미터

이름	위치	타입	필수	허용값	용도
id	path	string	예	—	대상 리소스의 식별자

요청 예시

GET /api/modules/gnuboard7-hello_module/admin/memos/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(gnuboard7-hello_module.memos.read)이 없는 경우
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

PUT /api/modules/gnuboard7-hello_module/admin/memos/{id}

• 라우트명: api.modules.gnuboard7-hello_module.admin.memos.update
• 컨트롤러: Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@update
• 인증/권한: auth:sanctum + permission:gnuboard7-hello_module.memos.update

요청 파라미터

이름	위치	타입	필수	허용값	용도
id	path	string	예	—	대상 리소스의 식별자
title	body	string	예	max 255	제목
content	body	string	예	—	본문 내용

요청 예시

PUT /api/modules/gnuboard7-hello_module/admin/memos/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "title": "예시 제목",
    "content": "예시 내용입니다."
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(gnuboard7-hello_module.memos.update)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

GET /api/modules/gnuboard7-hello_module/memos

• 라우트명: api.modules.gnuboard7-hello_module.memos.index
• 컨트롤러: Modules\Gnuboard7\HelloModule\Http\Controllers\Api\MemoController@index
• 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근)

요청 파라미터

이름	위치	타입	필수	허용값	용도
page	query	integer	아니오	min 1	조회할 페이지 번호 (1부터 시작)
per_page	query	integer	아니오	min 1, max 100	페이지당 항목 수

요청 예시

GET /api/modules/gnuboard7-hello_module/memos?page=1&per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

목록 응답: data.data[] 배열 항목의 필드.

필드	타입	실측 예시값	용도/설명
id	integer	2	기본 키 (내부 식별자)
uuid	string	4473e9ee-ecdf-4ad0-afb3-78ada47265af	외부 노출용 UUID (URL/API 식별자, 내부 id 비노출)
title	string	두 번째 메모	제목
content	string	Memo 엔티티의 CRUD 동작을 확인할 수 있는 추가 샘플입니다.	본문 내용
created_at	string	2026-07-31 22:09:15	생성 일시
updated_at	string	2026-07-31 22:09:15	최종 수정 일시
abilities	object	{"can_create":false,"can_update":false,"can_delete":false}	현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "메모를 조회했습니다.",
    "data": {
        "data": [
            {
                "id": 2,
                "uuid": "4473e9ee-ecdf-4ad0-afb3-78ada47265af",
                "title": "두 번째 메모",
                "content": "Memo 엔티티의 CRUD 동작을 확인할 수 있는 추가 샘플입니다.",
                "created_at": "2026-07-31 22:09:15",
                "updated_at": "2026-07-31 22:09:15",
                "abilities": {
                    "can_create": false,
                    "can_update": false,
                    "can_delete": false
                }
            },
            {
                "id": 1,
                "uuid": "86a29502-24cd-4124-a283-b0454d499fc1",
                "title": "환영합니다",
                "content": "Hello 모듈의 첫 번째 샘플 메모입니다. 학습용으로 제공됩니다.",
                "created_at": "2026-07-31 22:09:15",
                "updated_at": "2026-07-31 22:09:15",
                "abilities": {
                    "can_create": false,
                    "can_update": false,
                    "can_delete": false
                }
            },
            "... (총 25건 중 2건 표시)"
        ],
        "meta": {
            "current_page": 1,
            "last_page": 2,
            "per_page": 25,
            "total": 34
        },
        "abilities": {
            "can_create": false,
            "can_update": false,
            "can_delete": false
        }
    }
}

에러 응답

상태코드	의미	발생 조건
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

메모 목록을 페이지네이션으로 조회하는 공개 엔드포인트다. 라우트는 optional.sanctum 미들웨어를 쓰므로 비로그인 사용자도 조회할 수 있다(생성기 표기 auth:sanctum 은 실제와 다르며, 실제로는 토큰이 있으면 인증 컨텍스트를 붙이되 없어도 통과한다). 이 확장은 학습용 샘플로, 공개 읽기 API 의 표준 패턴(PublicBaseController + throttle:600,1)을 보여준다.

• 요청 파라미터: query per_page(정수, 기본 10)로 페이지 크기를 조절한다. FormRequest 를 쓰지 않고 컨트롤러가 $request->query('per_page', 10) 로 직접 읽는다.
• 응답: data 는 MemoCollection(BaseApiCollection) 산물로, data.data 에 MemoResource 배열, data.meta.pagination 에 페이지 메타(current_page/last_page/per_page/total/from/to/has_more_pages)를 담는다. 각 메모 항목 필드는 아래 상세 조회와 동일하다.
• 미설치 주의: 이 문서는 확장이 미설치인 상태에서 라우트 파일 정적 분석으로 생성되어 실측 응답이 없다(http-404). 설치 후 api:docgen --scope=module:gnuboard7-hello_module --seed 로 실측하면 응답 예시가 채워진다.

응답 예시 (정적 — MemoResource 구조 기준)

{
  "success": true,
  "data": {
    "data": [
      { "id": 1, "uuid": "…", "title": "샘플 메모", "content": "본문", "created_at": "…", "updated_at": "…", "is_owner": false, "abilities": { "can_create": false, "can_update": false, "can_delete": false } }
    ],
    "meta": { "pagination": { "current_page": 1, "last_page": 1, "per_page": 10, "total": 1, "from": 1, "to": 1, "has_more_pages": false } }
  },
  "message": "메모를 조회했습니다.",
  "error": null
}

GET /api/modules/gnuboard7-hello_module/memos/{id}

• 라우트명: api.modules.gnuboard7-hello_module.memos.show
• 컨트롤러: Modules\Gnuboard7\HelloModule\Http\Controllers\Api\MemoController@show
• 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근)

요청 파라미터

이름	위치	타입	필수	허용값	용도
id	path	string	예	—	대상 리소스의 식별자

요청 예시

GET /api/modules/gnuboard7-hello_module/memos/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드	의미	발생 조건
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

단일 메모를 조회하는 공개 엔드포인트다. 목록과 마찬가지로 optional.sanctum 이라 비로그인 조회가 허용된다(생성기 표기 auth:sanctum 은 실제와 다름).

• path 파라미터 {id}: 메모의 정수 PK. 라우트 제약 whereNumber('id') 로 숫자만 매칭된다. 라우트-모델 바인딩 없이 컨트롤러가 MemoService::getMemo($id) 로 직접 조회하므로, 존재하지 않으면 ModelNotFoundException → messages.memo.not_found(404).
• 응답: data 는 단건 MemoResource 다. 필드는 id(integer), uuid(string), title(string), content(string), 타임스탬프(created_at/updated_at), 그리고 BaseApiResource 공통 메타 is_owner(boolean) + abilities(can_create/can_update/can_delete — 각 권한 보유 여부). 권한 능력은 gnuboard7-hello_module.memos.{create,update,delete} 권한 매핑에서 파생된다.
• 미설치 주의: 이 문서는 미설치 상태 정적 분석으로 생성되어 실측 응답이 없다(unresolved-path-param — 실측할 실제 메모 레코드가 없음). 설치 후 --seed 실측 시 실제 값으로 채워진다.

응답 예시 (정적 — MemoResource 구조 기준)

{
  "success": true,
  "data": {
    "id": 1,
    "uuid": "…",
    "title": "샘플 메모",
    "content": "본문",
    "created_at": "…",
    "updated_at": "…",
    "is_owner": false,
    "abilities": { "can_create": false, "can_update": false, "can_delete": false }
  },
  "message": "메모를 조회했습니다.",
  "error": null
}