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(멱등).
This commit is contained in:
HeuJung committed 2026-08-06 13:54:35 +09:00
1 parent 3f2674f1a7
commit 403154167a
86 files changed
+186546 -700

No files matched your search

@@ -92,6 +92,63 @@ class ApiDocgenCommandTest extends TestCase
$this->assertContains('password', $names);
}
/**
* (c-2) 중첩 객체 파라미터(`refund_bank.bank_code`)도 추출합니다.
*
* 회귀: 배열 요소 규칙(`items.*.id`)을 상위 필드로 대표시키려는 스킵 조건이
* 점(`.`) 포함 여부만 봐서, 와일드카드가 없는 중첩 **객체** 필드까지 함께 버렸다.
* 그 결과 코어 환경설정(`general.*`·`mail.*`), 이커머스 주문(`orderer.*`·`refund_bank.*`) 등
* 17개 엔드포인트의 파라미터 수백 개가 문서에서 통째로 빠졌고, 사람이 수기로 채워 넣은
* 행은 재생성 때마다 다시 삭제됐다.
*/
#[Test]
public function 중첩_객체_파라미터를_추출하고_배열_요소는_상위로_대표시킨다(): void
{
$introspector = app(FormRequestIntrospector::class);
$rules = [
'payment_method' => 'required|string',
// 중첩 객체 — 문서에 개별 행으로 노출되어야 한다
'refund_bank.bank_code' => ['nullable', 'string', 'max:10'],
'refund_bank.holder' => ['nullable', 'string', 'max:50'],
// 배열 요소 — 상위(items)만 대표로 노출하고 개별 행은 만들지 않는다
'items' => 'array',
'items.*.id' => 'required|integer',
'items.*.qty' => 'required|integer',
];
$params = $this->invokeRulesToParams($introspector, $rules);
$names = array_column($params, 'name');
$this->assertContains('refund_bank.bank_code', $names, '중첩 객체 필드가 추출되어야 한다.');
$this->assertContains('refund_bank.holder', $names);
$this->assertContains('payment_method', $names);
$this->assertContains('items', $names);
$this->assertNotContains('items.*.id', $names, '배열 요소 규칙은 상위(items)로 대표시킨다.');
$this->assertNotContains('items.*.qty', $names);
// 추출된 중첩 필드도 타입/필수 메타를 갖는다
$bankCode = collect($params)->firstWhere('name', 'refund_bank.bank_code');
$this->assertSame('string', $bankCode['type']);
$this->assertFalse($bankCode['required']);
}
/**
* private rulesToParams 를 호출합니다 (규칙 배열 → 파라미터 메타 변환만 검증).
*
* @param FormRequestIntrospector $introspector 대상 인스턴스
* @param array<string, mixed> $rules 검증 규칙 배열
* @return array<int, array<string, mixed>> 파라미터 메타데이터 목록
*/
private function invokeRulesToParams(FormRequestIntrospector $introspector, array $rules): array
{
$method = new \ReflectionMethod($introspector, 'rulesToParams');
$method->setAccessible(true);
return $method->invoke($introspector, $rules);
}
/**
* (d) 재생성해도 사람이 채운 서술은 보존되고 추출 블록만 갱신됩니다(멱등).
*/