HeuJung
70452745c4
코드에만 존재하던 REST API 계약(약 663 엔드포인트)을 코어/확장 책임별로
분리된 마크다운 레퍼런스로 전면 문서화한다. 674개 규모에서 수기 문서는
반드시 drift 하므로 "코드 추출 → 스캐폴딩 → 사람이 서술 채움 → 하네스가
커버리지 강제" 하이브리드로 구성했다.
추출 파이프라인 (app/Support/ApiDoc):
- ApiRouteInventory / FormRequestIntrospector / ApiEndpointProbe(실측 HTTP) /
ResponseSchemaInferrer / ApiDocScaffolder / ColumnCommentResolver /
ResourceFieldDescriber / ParameterDescriber
- api:docgen 커맨드(--scope/--seed/--check/--dry-run/--base-url/--user) +
응답/파라미터 in-place 백필 커맨드 2종(재생성 없이 TODO 셀만 치환, 멱등)
- ApiDocSampleSeeder 계약 + 코어/확장 시더로 실측용 완전 샘플 멱등 생성
문서화 (실측 기반, GET read-only 실호출):
- 코어 291엔드포인트 35파일(docs/backend/api) + 규정 docs/backend/api-documentation.md
- 확장: ecommerce(231)·board(80)·page(17)·hello_module(2)·pay_kginicis(22)·
gdpr(15)·ckeditor5(2)·marketing(2)·verification_kginicis(1)
- 표준 4구성(헤더·요청 파라미터·응답 필드·에러 표) + 엔드포인트 용도 서술
- 파라미터 용도·응답 필드 설명 셀 전수 채움(도메인 지식 수기)
하네스:
- audit 룰 api-doc-coverage — API 표면(라우트/컨트롤러/FormRequest/Resource)
변경 시 대응 문서 미동반이면 차단. 전 대상 문서 완비로 error 승격
- file-rules 리마인더(컨트롤러/라우트 편집 시), coverage.json, dev-dashboard 카드
- docs/backend/routing.md 확장 공개 API URL 스킴 정정(/api/modules|plugins/{id})
- /AGENTS.md/docs-index 동기
34 lines
1.7 KiB
PHP
34 lines
1.7 KiB
PHP
<?php
|
|
|
|
namespace App\Contracts\ApiDoc;
|
|
|
|
/**
|
|
* API 문서 실측용 완전 샘플 시더 계약
|
|
*
|
|
* 확장(모듈/플러그인)이 자신의 API 도메인 대표 엔티티에 완전한 샘플 레코드를
|
|
* 멱등하게 생성하고, docgen 이 상세 GET 실측(path 파라미터 치환)에 사용할
|
|
* 도메인별 대표 route key 맵을 제공하기 위한 인터페이스입니다.
|
|
*
|
|
* 확장은 이 인터페이스를 구현한 클래스를 `{Namespace}\Support\ApiDoc\ApiDocSampleService`
|
|
* 규약 위치에 두며, `api:docgen --scope=module:{id}` 실행 시 커맨드가 자동으로 발견합니다.
|
|
* 코어의 `App\Support\ApiDoc\ApiDocSampleService` 도 동일 계약을 구현합니다.
|
|
*/
|
|
interface ApiDocSampleSeeder
|
|
{
|
|
/**
|
|
* 도메인별 완전 샘플을 멱등 생성하고 대표 route key 맵을 반환합니다.
|
|
*
|
|
* 반환 맵의 키는 라우트 도메인 그룹명(`domain_group`, 예: pages)이며,
|
|
* 값은 그 도메인의 상세 GET path 파라미터를 실측 가능한 실제 레코드로
|
|
* 치환하기 위한 모델 FQCN·route key 이름·route key 값입니다.
|
|
*
|
|
* 선택 필드 `path_params`(param 명 => 실제 값 맵)를 두면, route-model binding
|
|
* 도 도메인 폴백도 없는 문자열 path 파라미터(예: 게시판 slug 라우팅
|
|
* `boards/{slug}/posts/{id}`)를 param 명 정확 일치로 치환해 상세 GET 을
|
|
* 실측할 수 있습니다. 미제공 시 route key 기반 자동 치환만 적용됩니다.
|
|
*
|
|
* @return array<string, array{model: class-string, key: string, value: string, path_params?: array<string, string>}> 도메인 => 대표 레코드 정보
|
|
*/
|
|
public function seed(): array;
|
|
}
|