0 Fork 0

Files

T

HeuJung 403154167a fix(core): api:docgen 재생성이 문서를 손실·열화시키는 결함 수정

재생성이 사람이 채운 서술과 이전 실측 결과를 지우고, 코드가 바뀌지 않은
문서까지 매 실행마다 흔들던 결함 5건을 고쳤다.

- 중첩 객체 파라미터가 문서에서 통째로 누락되던 문제: 배열 요소(items.*.id)를
상위로 대표시키려던 스킵 조건이 점(.) 포함 여부만 봐서, 와일드카드가 없는
중첩 객체 필드(refund_bank.*, general.*, content.* 등 17개 엔드포인트 수백 개)
까지 함께 버렸다. 와일드카드가 있을 때만 스킵하도록 좁혔다.
- 사람이 보강한 에러 응답 표가 자동 추론 초안에 덮여 사라지던 문제:
상태코드 키 단위로 병합한다.
- 실측 실패가 이전에 관측해 둔 응답 예시를 지우던 문제: 실측 성패는 호출 시점
데이터 유무에 좌우되므로(DELETE /checkout 은 대상이 없으면 404), 실패는
"새로 관측하지 못했다"는 뜻이지 기존 관측이 무효라는 뜻이 아니다.
- 실측 예시값·응답 예시 JSON 이 DB 상태를 그대로 반영해 비멱등하던 문제:
값이 아니라 스펙(필드 집합·타입)이 바뀐 경우에만 갱신한다. nullable 이
null 로 관측된 것은 타입 변경이 아니므로 기존 값을 유지한다.
- 요청 예시 path 파라미터가 실측 성패에 따라 흔들리던 문제: placeholder 로 고정.

결과: 문서 63개 전수 대조에서 손실 0(서술·표 셀·응답 예시), 전 scope 연속
재생성 시 diff 0(멱등).

2026-08-06 13:54:35 +09:00

17 KiB

Raw Blame History

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
}

17 KiB Raw Blame History

Memos API 레퍼런스

TL;DR (5초 요약)

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

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

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

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

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

GET /api/modules/gnuboard7-hello_module/memos

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

17 KiB

Raw Blame History