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:
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) 재생성해도 사람이 채운 서술은 보존되고 추출 블록만 갱신됩니다(멱등).
|
||||
*/
|
||||
|
||||
Reference in new issue
Block a user