docs: API 레퍼런스 진입점 정비 + README 데모 링크 추가
최상위 README 의 "API 레퍼런스" 가 문서 작성 규정(api-documentation.md)을 가리켜, 개발자·AI 가 실제 엔드포인트 레퍼런스에 도달할 경로가 없었다. 코어 목차(docs/backend/api/README.md)도 어느 인덱스에서도 참조되지 않았고, 확장 API 문서 9종 역시 공개 진입점이 없었다. 코어 목차를 코어+확장 통합 진입 문서로 승격하고, 상단에 공통 규약(인증· 응답 봉투·페이지네이션·에러)을 실측 근거로 서술했다. 확장 목차는 파일 시스템 패턴 스캔으로 생성해 확장명 하드코딩을 두지 않았고, --scope 를 좁혀 실행해도 개요와 확장 표가 소실되지 않도록 보존 경로를 분리했다. 아울러 설치 없이 동작을 확인할 수 있도록 README 상단에 데모 사이트와 관리자 데모 링크를 추가했다.
This commit is contained in:
1 parent
45bf59472a
commit
5f3b904aab
9 files changed
+593
-15
No files matched your search
@@ -144,6 +144,15 @@
|
||||
| [e2e-testing.md](docs/testing/e2e-testing.md) | 그누보드7 Playwright E2E 테스트 가이드 | - |
|
||||
|
||||
|
||||
### API 레퍼런스 진입점
|
||||
|
||||
> 엔드포인트별 요청 파라미터·응답 필드·요청/응답 예시. 공통 규약(Bearer 토큰 인증, 응답 봉투, 페이지네이션, 401/403/422/428)은 진입점 문서 상단에 정리되어 있다.
|
||||
|
||||
| 대상 | 진입점 | 문서/엔드포인트 |
|
||||
|------|--------|----------------|
|
||||
| 코어 | [docs/backend/api/README.md](docs/backend/api/README.md) | 35 / 291 |
|
||||
|
||||
|
||||
### 확장 API 레퍼런스 (9개 확장, 자동 스캔)
|
||||
|
||||
> 각 확장이 소유하는 API 문서 목차. `php artisan api:docgen` 이 생성하며, 이 표는 `{modules,plugins}/_bundled/*/docs/api/README.md` 를 패턴 스캔해 자동 편입된다(확장명 하드코딩 없음).
|
||||
|
||||
@@ -16,6 +16,11 @@
|
||||
<a href="#"><img src="https://img.shields.io/badge/status-Stable-brightgreen" alt="Status"></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://g7.gnuboard.com"><strong>데모 사이트</strong></a> ·
|
||||
<a href="https://g7.gnuboard.com/admin"><strong>관리자 데모</strong></a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
[소개](#그누보드7-소개) · [주요 기능](#주요-기능) · [기술 스택](#기술-스택) · [아키텍처](#아키텍처) · [빠른 시작](#빠른-시작) · [기본 제공 확장](#기본-제공-확장) · [비즈니스 모델](#비즈니스-모델) · [기존 사용자](#기존-그누보드-사용자) · [문서](#문서) · [기여하기](#기여하기) · [만든 사람들](#만든-사람들) · [커뮤니티](#커뮤니티) · [변경 기록](#변경-기록) · [라이선스](#라이선스)
|
||||
@@ -462,7 +467,8 @@ cp .env.example .env
|
||||
| 플러그인 개발 | [docs/extension/plugin-development.md](docs/extension/plugin-development.md) |
|
||||
| 템플릿 개발 | [docs/extension/template-basics.md](docs/extension/template-basics.md) |
|
||||
| 테스트 | [docs/testing-guide.md](docs/testing-guide.md) |
|
||||
| API 레퍼런스 | [docs/backend/api-documentation.md](docs/backend/api-documentation.md) |
|
||||
| API 레퍼런스 | [docs/backend/api/README.md](docs/backend/api/README.md) |
|
||||
| API 문서 작성 규정 | [docs/backend/api-documentation.md](docs/backend/api-documentation.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -228,12 +228,28 @@ class ApiDocgenCommand extends Command
|
||||
// 대상별 API 문서 목차(README.md) 생성/갱신 — 확장 API 레퍼런스 발견성의 규약 진입점.
|
||||
// check/dry-run 은 파일을 쓰지 않으므로 제외. examples-only 는 목차도 최신화한다.
|
||||
if (! $this->option('check')) {
|
||||
$coreReadme = $this->readmeFile(['type' => 'core', 'id' => null]);
|
||||
|
||||
foreach ($readmeIndex as $readmePath => $meta) {
|
||||
$existing = File::exists($readmePath) ? File::get($readmePath) : null;
|
||||
$content = $scaffolder->readmeIndex($meta['label'], $meta['entries'], $existing);
|
||||
// 코어 README 는 최상위 README 의 "API 레퍼런스" 진입점이므로 확장 목차를 함께 싣는다.
|
||||
$extensions = $readmePath === $coreReadme ? $this->scanExtensionApiReadmes() : null;
|
||||
$content = $scaffolder->readmeIndex($meta['label'], $meta['entries'], $existing, $extensions);
|
||||
File::ensureDirectoryExists(dirname($readmePath));
|
||||
File::put($readmePath, $content);
|
||||
}
|
||||
|
||||
// 확장 스코프 실행이라 코어 README 를 다시 쓰지 않았어도, 그 확장의 엔드포인트 수가
|
||||
// 바뀌었을 수 있으므로 코어 README 의 확장 목차 블록만 in-place 갱신한다.
|
||||
if (! array_key_exists($coreReadme, $readmeIndex) && File::exists($coreReadme)) {
|
||||
$updated = $scaffolder->refreshExtensionIndex(
|
||||
File::get($coreReadme),
|
||||
$this->scanExtensionApiReadmes()
|
||||
);
|
||||
if ($updated !== null) {
|
||||
File::put($coreReadme, $updated);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if ($this->option('check')) {
|
||||
@@ -816,6 +832,56 @@ class ApiDocgenCommand extends Command
|
||||
return base_path("{$base}/_bundled/{$owner['id']}/docs/api/{$domain}.md");
|
||||
}
|
||||
|
||||
/**
|
||||
* 번들 확장이 소유한 API 문서 목차(README.md)를 파일 시스템 패턴 스캔으로 수집합니다.
|
||||
*
|
||||
* 확장명을 하드코딩하지 않고 `{modules,plugins}/_bundled/{*}/docs/api/README.md` 존재
|
||||
* 여부만으로 발견한다(동적 로딩 원칙). 문서 수·엔드포인트 수는 스캐폴더가 방출한
|
||||
* 집계 라인(`**문서 수**: N · **엔드포인트 수**: M`)에서 읽는다.
|
||||
*
|
||||
* 링크 경로는 코어 README(`docs/backend/api/`) 기준 상대경로로 만든다.
|
||||
*
|
||||
* @return array<int, array{id: string, type: string, path: string, docs: int, endpoints: int}> 확장 목록
|
||||
*/
|
||||
private function scanExtensionApiReadmes(): array
|
||||
{
|
||||
$results = [];
|
||||
|
||||
foreach (['modules' => 'module', 'plugins' => 'plugin'] as $dir => $type) {
|
||||
$bundled = base_path("{$dir}/_bundled");
|
||||
if (! File::isDirectory($bundled)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
foreach (File::directories($bundled) as $extDir) {
|
||||
$readme = $extDir.DIRECTORY_SEPARATOR.'docs'.DIRECTORY_SEPARATOR.'api'.DIRECTORY_SEPARATOR.'README.md';
|
||||
if (! File::exists($readme)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$id = basename($extDir);
|
||||
$content = File::get($readme);
|
||||
$docs = 0;
|
||||
$endpoints = 0;
|
||||
if (preg_match('/\*\*문서 수\*\*:\s*(\d+)\s*·\s*\*\*엔드포인트 수\*\*:\s*(\d+)/u', $content, $m)) {
|
||||
$docs = (int) $m[1];
|
||||
$endpoints = (int) $m[2];
|
||||
}
|
||||
|
||||
$results[] = [
|
||||
'id' => $id,
|
||||
'type' => $type,
|
||||
// docs/backend/api/README.md → 프로젝트 루트까지 3단계 상위
|
||||
'path' => "../../../{$dir}/_bundled/{$id}/docs/api/README.md",
|
||||
'docs' => $docs,
|
||||
'endpoints' => $endpoints,
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
return $results;
|
||||
}
|
||||
|
||||
/**
|
||||
* 소유 대상의 API 문서 목차(README.md) 경로를 반환합니다.
|
||||
*
|
||||
|
||||
@@ -116,6 +116,16 @@ class ApiDocScaffolder
|
||||
return implode("\n", $lines)."\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* @var string 코어 README 의 확장 API 목차 생성 블록 키
|
||||
*/
|
||||
private const GEN_KEY_EXTENSIONS = 'api-readme-extensions';
|
||||
|
||||
/**
|
||||
* @var string 코어/확장 README 의 도메인 목차 생성 블록 키
|
||||
*/
|
||||
private const GEN_KEY_INDEX = 'api-readme-index';
|
||||
|
||||
/**
|
||||
* 대상(코어/확장)의 API 문서 디렉토리 목차(README.md)를 생성합니다.
|
||||
*
|
||||
@@ -124,13 +134,23 @@ class ApiDocScaffolder
|
||||
* 갱신되며, 블록 밖 사람 서술(개요·주의사항)은 보존한다. 확장 API 문서의 발견성은
|
||||
* 코어 인덱스 생성기가 이 README 를 패턴 스캔(확장명 하드코딩 없이)해 확보한다.
|
||||
*
|
||||
* 코어 README 는 프로젝트 최상위 `README.md` 의 "API 레퍼런스" 진입점이므로,
|
||||
* 도메인 목차 뒤에 확장 API 목차 블록을 함께 싣는다. `$extensions` 가 null 이면
|
||||
* 확장 블록을 생성하지 않고 기존 블록(있으면)을 그대로 보존한다 — `--scope` 축소
|
||||
* 실행이 확장 목차를 소실시키지 않도록 하기 위함이다.
|
||||
*
|
||||
* @param string $ownerLabel 소유 라벨 (예: '코어', '모듈 `sirsoft-ecommerce`')
|
||||
* @param array<int, array{domain: string, file: string, count: int}> $entries 도메인 파일 목록
|
||||
* @param string|null $existing 기존 README (사람 서술 보존용, 없으면 null)
|
||||
* @param array<int, array{id: string, type: string, path: string, docs: int, endpoints: int}>|null $extensions 확장 API 목차 항목 (코어 전용, 미갱신 시 null)
|
||||
* @return string README 마크다운
|
||||
*/
|
||||
public function readmeIndex(string $ownerLabel, array $entries, ?string $existing = null): string
|
||||
{
|
||||
public function readmeIndex(
|
||||
string $ownerLabel,
|
||||
array $entries,
|
||||
?string $existing = null,
|
||||
?array $extensions = null
|
||||
): string {
|
||||
usort($entries, fn ($a, $b) => strcmp($a['domain'], $b['domain']));
|
||||
$total = array_sum(array_column($entries, 'count'));
|
||||
|
||||
@@ -139,13 +159,21 @@ class ApiDocScaffolder
|
||||
$rows[] = "| [{$e['file']}]({$e['file']}) | `{$e['domain']}` | {$e['count']} |";
|
||||
}
|
||||
|
||||
$genKey = 'api-readme-index';
|
||||
$genKey = self::GEN_KEY_INDEX;
|
||||
$lines = [];
|
||||
$lines[] = '# API 레퍼런스 문서 목차';
|
||||
$lines[] = '';
|
||||
$lines[] = "> **소유**: {$ownerLabel} · **생성**: `php artisan api:docgen` (실측 기반).";
|
||||
$lines[] = '> 아래 표는 자동 생성됩니다. 각 문서를 열면 엔드포인트별 파라미터·응답·예시를 볼 수 있습니다.';
|
||||
$lines[] = '';
|
||||
|
||||
// 헤더와 목차 표 사이의 사람 개요(공통 규약 등)를 보존/삽입한다.
|
||||
$overview = $existing !== null ? $this->extractReadmeOverview($existing, $genKey) : null;
|
||||
if ($overview !== null && $overview !== '') {
|
||||
$lines[] = $overview;
|
||||
$lines[] = '';
|
||||
}
|
||||
|
||||
$lines[] = self::GEN_START.$genKey.' -->';
|
||||
$lines[] = '- **문서 수**: '.count($entries)." · **엔드포인트 수**: {$total}";
|
||||
$lines[] = '';
|
||||
@@ -156,15 +184,98 @@ class ApiDocScaffolder
|
||||
|
||||
$generated = implode("\n", $lines)."\n";
|
||||
|
||||
// 블록 밖 사람 서술(개요 등)이 있으면 보존한다.
|
||||
$prose = $existing !== null ? $this->extractHumanProse($existing, $genKey) : null;
|
||||
// 목차 블록 밖 사람 서술(주의사항 등)이 있으면 보존한다.
|
||||
// 확장 목차(`## 확장 API 레퍼런스`) 이후는 별도 블록이므로 삼키지 않는다.
|
||||
$prose = $existing !== null ? $this->extractReadmeTrailingProse($existing, $genKey) : null;
|
||||
if ($prose !== null && $prose !== '') {
|
||||
$generated .= "\n".$prose."\n";
|
||||
}
|
||||
|
||||
$extensionBlock = $extensions !== null
|
||||
? $this->extensionIndexBlock($extensions)
|
||||
: ($existing !== null ? $this->extractGeneratedBlock($existing, self::GEN_KEY_EXTENSIONS) : null);
|
||||
|
||||
if ($extensionBlock !== null) {
|
||||
$generated = rtrim($generated)."\n\n".trim($extensionBlock)."\n";
|
||||
}
|
||||
|
||||
return $generated;
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 코어 README 에서 확장 API 목차 블록만 in-place 갱신합니다.
|
||||
*
|
||||
* 확장 스코프 실행(`--scope=module:...`)이라 코어 도메인 목차를 재생성하지 않는 경우에도,
|
||||
* 그 확장의 문서 수·엔드포인트 수 변동을 코어 진입점에 반영하기 위해 사용한다.
|
||||
* 코어 README 에 확장 블록이 아직 없으면 문서 끝에 새로 덧붙인다.
|
||||
*
|
||||
* @param string $existing 기존 코어 README
|
||||
* @param array<int, array{id: string, type: string, path: string, docs: int, endpoints: int}> $extensions 확장 목록
|
||||
* @return string|null 갱신된 README (변경 없으면 null)
|
||||
*/
|
||||
public function refreshExtensionIndex(string $existing, array $extensions): ?string
|
||||
{
|
||||
$block = $this->extensionIndexBlock($extensions);
|
||||
$current = $this->extractGeneratedBlock($existing, self::GEN_KEY_EXTENSIONS);
|
||||
|
||||
if ($current === null) {
|
||||
return rtrim($existing)."\n\n".$block;
|
||||
}
|
||||
|
||||
if (trim($current) === trim($block)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return str_replace($current, trim($block), $existing);
|
||||
}
|
||||
|
||||
/**
|
||||
* 코어 README 의 확장 API 목차 블록을 생성합니다.
|
||||
*
|
||||
* 확장명을 하드코딩하지 않고, 커맨드가 `{modules,plugins}/_bundled/*\/docs/api/README.md`
|
||||
* 를 스캔해 넘긴 목록을 그대로 표로 만든다.
|
||||
*
|
||||
* @param array<int, array{id: string, type: string, path: string, docs: int, endpoints: int}> $extensions 확장 목록
|
||||
* @return string 확장 목차 마크다운 블록 (@generated 경계 포함)
|
||||
*/
|
||||
private function extensionIndexBlock(array $extensions): string
|
||||
{
|
||||
usort($extensions, function ($a, $b) {
|
||||
return [$a['type'], $a['id']] <=> [$b['type'], $b['id']];
|
||||
});
|
||||
|
||||
$lines = [];
|
||||
$lines[] = '## 확장 API 레퍼런스';
|
||||
$lines[] = '';
|
||||
$lines[] = '> 각 확장이 자신의 API 문서를 소유합니다. 아래 표는 자동 생성됩니다.';
|
||||
$lines[] = '';
|
||||
$lines[] = self::GEN_START.self::GEN_KEY_EXTENSIONS.' -->';
|
||||
|
||||
if ($extensions === []) {
|
||||
$lines[] = '_설치된 번들 확장 중 API 문서를 소유한 확장이 없습니다._';
|
||||
$lines[] = '';
|
||||
$lines[] = self::GEN_END;
|
||||
|
||||
return implode("\n", $lines)."\n";
|
||||
}
|
||||
|
||||
$lines[] = '- **확장 수**: '.count($extensions)
|
||||
.' · **엔드포인트 수**: '.array_sum(array_column($extensions, 'endpoints'));
|
||||
$lines[] = '';
|
||||
$lines[] = '| 확장 | 유형 | API 문서 목차 | 문서/엔드포인트 |';
|
||||
$lines[] = '| --- | --- | --- | --- |';
|
||||
|
||||
foreach ($extensions as $e) {
|
||||
$type = $e['type'] === 'module' ? '모듈' : '플러그인';
|
||||
$lines[] = "| `{$e['id']}` | {$type} | [docs/api/]({$e['path']}) | {$e['docs']} / {$e['endpoints']} |";
|
||||
}
|
||||
|
||||
$lines[] = '';
|
||||
$lines[] = self::GEN_END;
|
||||
|
||||
return implode("\n", $lines)."\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* 인증/권한 라인을 구성합니다.
|
||||
*
|
||||
@@ -832,6 +943,99 @@ class ApiDocScaffolder
|
||||
return $merged;
|
||||
}
|
||||
|
||||
/**
|
||||
* README 헤더(인용 블록)와 첫 생성 블록 사이의 사람 개요를 추출합니다.
|
||||
*
|
||||
* 개요(공통 규약: 인증·응답 봉투·에러·페이지네이션)는 목차 표보다 먼저 읽혀야 하므로
|
||||
* 생성 블록 앞에 둔다. 재생성 시 이 구간을 원문 그대로 되살려 사람 서술을 보존한다.
|
||||
*
|
||||
* @param string $existing 기존 README
|
||||
* @param string $key 목차 생성 블록 키
|
||||
* @return string|null 보존할 개요 (없으면 null)
|
||||
*/
|
||||
private function extractReadmeOverview(string $existing, string $key): ?string
|
||||
{
|
||||
$startPos = strpos($existing, self::GEN_START.$key.' -->');
|
||||
if ($startPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$head = substr($existing, 0, $startPos);
|
||||
|
||||
// 헤더 인용 블록(`> ...`) 의 마지막 줄 이후가 사람 개요다.
|
||||
if (! preg_match_all('/(?:^|\n)>[^\n]*/', $head, $all, PREG_OFFSET_CAPTURE)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$last = end($all[0]);
|
||||
$overview = trim(substr($head, $last[1] + strlen($last[0])));
|
||||
|
||||
return $overview === '' ? null : $overview;
|
||||
}
|
||||
|
||||
/**
|
||||
* README 목차 블록 뒤 ~ 확장 목차 헤딩 앞의 사람 서술을 추출합니다.
|
||||
*
|
||||
* @param string $existing 기존 README
|
||||
* @param string $key 목차 생성 블록 키
|
||||
* @return string|null 보존할 사람 서술 (없으면 null)
|
||||
*/
|
||||
private function extractReadmeTrailingProse(string $existing, string $key): ?string
|
||||
{
|
||||
$startPos = strpos($existing, self::GEN_START.$key.' -->');
|
||||
if ($startPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$endPos = strpos($existing, self::GEN_END, $startPos);
|
||||
if ($endPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$afterGen = substr($existing, $endPos + strlen(self::GEN_END));
|
||||
|
||||
// 확장 목차 섹션(`## 확장 API 레퍼런스`)부터는 생성 블록 소관이므로 제외한다.
|
||||
$nextSection = preg_match('/\n## /', $afterGen, $m, PREG_OFFSET_CAPTURE)
|
||||
? $m[0][1]
|
||||
: strlen($afterGen);
|
||||
|
||||
$prose = trim(substr($afterGen, 0, $nextSection));
|
||||
|
||||
return $prose === '' ? null : $prose;
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 문서에서 지정 키의 생성 블록을 헤딩·인용문 포함해 원문 그대로 추출합니다.
|
||||
*
|
||||
* `--scope` 축소 실행 등으로 이번 회차에 갱신 대상이 아닌 블록을 소실 없이 되살린다.
|
||||
*
|
||||
* @param string $existing 기존 문서
|
||||
* @param string $key 생성 블록 키
|
||||
* @return string|null 블록 원문 (없으면 null)
|
||||
*/
|
||||
private function extractGeneratedBlock(string $existing, string $key): ?string
|
||||
{
|
||||
$startPos = strpos($existing, self::GEN_START.$key.' -->');
|
||||
if ($startPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$endPos = strpos($existing, self::GEN_END, $startPos);
|
||||
if ($endPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// 블록 앞의 섹션 헤딩(`## ...`)부터 함께 되살린다.
|
||||
$head = substr($existing, 0, $startPos);
|
||||
$headingPos = preg_match_all('/(?:^|\n)## [^\n]*/', $head, $all, PREG_OFFSET_CAPTURE)
|
||||
? end($all[0])[1]
|
||||
: null;
|
||||
|
||||
$from = $headingPos !== null ? $headingPos : $startPos;
|
||||
|
||||
return trim(substr($existing, $from, ($endPos + strlen(self::GEN_END)) - $from));
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 문서에서 특정 엔드포인트의 사람 서술(생성 블록 밖)을 추출합니다.
|
||||
*
|
||||
|
||||
@@ -19,6 +19,18 @@
|
||||
|
||||
---
|
||||
|
||||
## API 레퍼런스
|
||||
|
||||
G7 이 제공하는 REST API 의 엔드포인트별 요청 파라미터·응답 필드·요청/응답 예시입니다.
|
||||
템플릿의 `data_sources` 를 작성하거나 외부에서 G7 을 연동할 때 참고하세요.
|
||||
|
||||
| 문서 | 설명 |
|
||||
|------|------|
|
||||
| [backend/api/README.md](backend/api/README.md) | **API 레퍼런스 진입점** — 공통 규약(인증·응답 봉투·페이지네이션·에러) + 코어/확장 전체 목차 |
|
||||
| [backend/api-documentation.md](backend/api-documentation.md) | API 문서 작성·갱신 규정 (기여자용) |
|
||||
|
||||
---
|
||||
|
||||
## 작업 유형별 필수 문서
|
||||
|
||||
### 레이아웃 JSON 작성
|
||||
|
||||
@@ -15,6 +15,16 @@
|
||||
|
||||
---
|
||||
|
||||
## API 레퍼런스
|
||||
|
||||
엔드포인트별 요청 파라미터·응답 필드·요청/응답 예시는 [api/README.md](api/README.md) 에 있습니다.
|
||||
공통 규약(Bearer 토큰 인증, 응답 봉투, 페이지네이션, 401/403/422/428 에러)도 그 문서 상단에 정리되어 있습니다.
|
||||
확장(모듈·플러그인)이 소유한 API 문서 목록도 같은 문서에서 찾을 수 있습니다.
|
||||
|
||||
문서 작성·갱신 규정은 [api-documentation.md](api-documentation.md) 를 참고하세요.
|
||||
|
||||
---
|
||||
|
||||
<!-- AUTO-GENERATED-START: backend-readme-docs -->
|
||||
## 문서 목록
|
||||
|
||||
|
||||
@@ -54,20 +54,39 @@ G7 의 REST API 는 라우트 `->name()` 규약은 있으나 엔드포인트별
|
||||
### 문서 목차와 발견성 (README.md 규약)
|
||||
|
||||
각 대상(코어·확장)의 API 문서 디렉토리에는 `README.md` 목차가 있어야 한다. `api:docgen` 이 도메인 파일
|
||||
목록·엔드포인트 수를 담아 자동 생성한다(`@generated` 블록, 재생성 멱등, 블록 밖 사람 개요는 보존).
|
||||
목록·엔드포인트 수를 담아 자동 생성한다(`@generated` 블록, 재생성 멱등, 블록 밖 사람 서술은 보존).
|
||||
|
||||
- 코어: `docs/backend/api/README.md`
|
||||
- 확장: `{modules|plugins}/_bundled/{id}/docs/api/README.md`
|
||||
|
||||
확장 API 문서의 발견성은 이 목차를 통해 확보한다. 코어 인덱스 생성기(`generate-docs-index.cjs`)는
|
||||
확장명을 하드코딩하지 않고 `{modules,plugins}/_bundled/*/docs/api/README.md` 를 **패턴 스캔**해,
|
||||
CLAUDE.md·AGENTS.md·docs-index 의 "확장 API 레퍼런스" 표에 자동 편입한다(동적 로딩 원칙 — 코어는 규약과
|
||||
스캔 패턴만, 확장 이름은 파일 시스템에서 발견). 처음 진입하는 개발자/AI 의 도달 경로:
|
||||
코어 README 는 프로젝트 최상위 `README.md` 의 "API 레퍼런스" 진입점이다. 따라서 확장 목차와 달리 세
|
||||
부분으로 구성된다. 이 문서(작성 규정)와 혼동되지 않도록 최상위 `README.md` 는 둘을 "API 레퍼런스" 와
|
||||
"API 문서 작성 규정" 으로 분리해 링크한다.
|
||||
|
||||
| 구성 | 위치 | 소유 |
|
||||
| --- | --- | --- |
|
||||
| 공통 규약 개요 (인증·응답 봉투·페이지네이션·에러) | 헤더 인용 블록 뒤 ~ 첫 `@generated` 앞 | 사람 (재생성 시 원문 보존) |
|
||||
| 코어 도메인 목차 | `@generated:start:api-readme-index` | `api:docgen` |
|
||||
| 확장 API 목차 | `@generated:start:api-readme-extensions` | `api:docgen` (코어 README 전용) |
|
||||
|
||||
개요를 첫 생성 블록 앞에 두는 이유는 목차 표보다 먼저 읽혀야 하기 때문이다. 확장 README 에는 확장 목차
|
||||
블록을 넣지 않는다. `--scope` 를 좁혀 실행해도 이번 회차에 갱신하지 않는 블록과 사람 서술은 원문 그대로
|
||||
보존된다.
|
||||
|
||||
확장 API 문서의 발견성은 이 목차를 통해 확보한다. `api:docgen` 과 코어 인덱스 생성기
|
||||
(`generate-docs-index.cjs`) 는 확장명을 하드코딩하지 않고
|
||||
`{modules,plugins}/_bundled/*/docs/api/README.md` 를 **패턴 스캔**해, 코어 README 의 "확장 API 레퍼런스"
|
||||
표와 CLAUDE.md·AGENTS.md·docs-index 에 자동 편입한다(동적 로딩 원칙 — 코어는 규약과 스캔 패턴만, 확장
|
||||
이름은 파일 시스템에서 발견). 문서 수·엔드포인트 수는 각 README 의 집계 라인
|
||||
(`**문서 수**: N · **엔드포인트 수**: M`)에서 읽으므로, 이 라인 형식을 바꾸면 두 스캐너를 함께 갱신한다.
|
||||
|
||||
처음 진입하는 개발자/AI 의 도달 경로:
|
||||
|
||||
```text
|
||||
CLAUDE.md "확장 API 레퍼런스" 표 (자동 스캔)
|
||||
→ {확장}/docs/api/README.md (확장 소유 목차)
|
||||
→ {도메인}.md (엔드포인트별 파라미터·응답·예시)
|
||||
README.md "API 레퍼런스" 또는 CLAUDE.md "API 레퍼런스 진입점" 표
|
||||
→ docs/backend/api/README.md (공통 규약 + 코어 목차 + 확장 목차)
|
||||
→ {도메인}.md 또는 {확장}/docs/api/README.md
|
||||
→ 엔드포인트별 파라미터·응답·예시
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -3,6 +3,110 @@
|
||||
> **소유**: 코어 · **생성**: `php artisan api:docgen` (실측 기반).
|
||||
> 아래 표는 자동 생성됩니다. 각 문서를 열면 엔드포인트별 파라미터·응답·예시를 볼 수 있습니다.
|
||||
|
||||
G7 의 REST API 레퍼런스입니다. 도메인별 문서에는 엔드포인트마다 메서드·URI·인증/권한, 요청 파라미터 표,
|
||||
응답 필드 표, 실제 호출로 관측한 요청·응답 예시가 실려 있습니다. 아래 공통 규약은 모든 엔드포인트에
|
||||
동일하게 적용되므로 개별 문서에서 반복하지 않습니다.
|
||||
|
||||
문서 작성·갱신 규정은 [api-documentation.md](../api-documentation.md) 를 참고하세요.
|
||||
|
||||
## 공통 규약
|
||||
|
||||
### 인증
|
||||
|
||||
Laravel Sanctum 의 **Bearer 토큰 전용**입니다(세션 쿠키 인증 미사용).
|
||||
`POST /api/auth/login` 또는 `POST /api/auth/admin/login` 으로 토큰을 발급받아 모든 후속 요청에 실어 보냅니다.
|
||||
|
||||
```http
|
||||
GET /api/me HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
```
|
||||
|
||||
각 문서의 **인증/권한** 줄은 다음 네 가지 중 하나입니다.
|
||||
|
||||
| 표기 | 의미 |
|
||||
| --- | --- |
|
||||
| `공개 (인증 불필요)` | 토큰 없이 호출 가능 |
|
||||
| `optional.sanctum` | 토큰이 있으면 회원, 없으면 비회원으로 처리 (둘 다 접근 가능) |
|
||||
| `auth:sanctum` | 유효한 토큰 필수 (없거나 만료 시 401) |
|
||||
| `auth:sanctum + admin + permission:{키}` | 토큰 + 관리자 + 해당 권한 필요 (권한 부족 시 403) |
|
||||
|
||||
### 로케일
|
||||
|
||||
응답 메시지의 언어는 ① 로그인 사용자의 `users.language` → ② `Accept-Language` 헤더 →
|
||||
③ 시스템 기본값(`config('app.locale')`) 순으로 결정됩니다. 지원 언어는 `config('app.supported_locales')` 를 따릅니다.
|
||||
|
||||
### 응답 봉투
|
||||
|
||||
성공·실패 모두 동일한 최상위 구조를 씁니다. 실제 페이로드는 항상 `data` 안에 들어갑니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "요청이 성공했습니다.",
|
||||
"data": { }
|
||||
}
|
||||
```
|
||||
|
||||
실패 시 `success` 는 `false` 이고, 검증 오류는 `errors` 에 필드별 메시지 배열로 담깁니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "입력값이 올바르지 않습니다.",
|
||||
"errors": {
|
||||
"email": ["이메일 형식이 올바르지 않습니다."]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 페이지네이션
|
||||
|
||||
목록 엔드포인트는 `data.data[]` 에 항목 배열을, `data.pagination` 에 페이지 정보를 담습니다.
|
||||
요청은 `page` 와 `per_page` 쿼리 파라미터로 제어합니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"pagination": {
|
||||
"current_page": 1,
|
||||
"last_page": 4,
|
||||
"per_page": 25,
|
||||
"total": 87,
|
||||
"from": 1,
|
||||
"to": 25,
|
||||
"has_more_pages": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
일부 목록은 `data.abilities` 에 컬렉션 레벨 권한(`can_create`, `can_delete` 등)을 함께 반환합니다.
|
||||
화면의 버튼 노출 여부를 이 값으로 판정하세요.
|
||||
|
||||
### 공통 에러 상태코드
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 엔드포인트가 요구하는 권한이 없는 경우 |
|
||||
| 404 | Not Found | 대상 리소스가 없거나 접근 범위를 벗어난 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`errors` 에 필드별 메시지) |
|
||||
| 428 | Precondition Required | 본인인증(IDV)이 선행되어야 하는 경우 |
|
||||
|
||||
428 응답은 `error_code: "identity_verification_required"` 와 함께 `verification` 객체를 반환합니다.
|
||||
클라이언트는 이 값으로 본인인증 화면을 띄운 뒤 원래 요청을 재시도합니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error_code": "identity_verification_required",
|
||||
"message": "본인인증이 필요합니다.",
|
||||
"verification": { }
|
||||
}
|
||||
```
|
||||
|
||||
## 코어 API 레퍼런스
|
||||
|
||||
<!-- @generated:start:api-readme-index -->
|
||||
- **문서 수**: 35 · **엔드포인트 수**: 291
|
||||
|
||||
@@ -46,3 +150,23 @@
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
## 확장 API 레퍼런스
|
||||
|
||||
> 각 확장이 자신의 API 문서를 소유합니다. 아래 표는 자동 생성됩니다.
|
||||
|
||||
<!-- @generated:start:api-readme-extensions -->
|
||||
- **확장 수**: 9 · **엔드포인트 수**: 372
|
||||
|
||||
| 확장 | 유형 | API 문서 목차 | 문서/엔드포인트 |
|
||||
| --- | --- | --- | --- |
|
||||
| `gnuboard7-hello_module` | 모듈 | [docs/api/](../../../modules/_bundled/gnuboard7-hello_module/docs/api/README.md) | 1 / 2 |
|
||||
| `sirsoft-board` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-board/docs/api/README.md) | 10 / 80 |
|
||||
| `sirsoft-ecommerce` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-ecommerce/docs/api/README.md) | 33 / 231 |
|
||||
| `sirsoft-page` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-page/docs/api/README.md) | 2 / 17 |
|
||||
| `sirsoft-ckeditor5` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-ckeditor5/docs/api/README.md) | 2 / 2 |
|
||||
| `sirsoft-gdpr` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-gdpr/docs/api/README.md) | 4 / 15 |
|
||||
| `sirsoft-marketing` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-marketing/docs/api/README.md) | 2 / 2 |
|
||||
| `sirsoft-pay_kginicis` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-pay_kginicis/docs/api/README.md) | 5 / 22 |
|
||||
| `sirsoft-verification_kginicis` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-verification_kginicis/docs/api/README.md) | 1 / 1 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -161,4 +161,132 @@ class ApiDocgenCommandTest extends TestCase
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* README 목차 항목/확장 목록 샘플을 반환합니다.
|
||||
*
|
||||
* @return array{0: array<int, array{domain: string, file: string, count: int}>, 1: array<int, array{id: string, type: string, path: string, docs: int, endpoints: int}>}
|
||||
*/
|
||||
private function readmeFixtures(): array
|
||||
{
|
||||
$entries = [
|
||||
['domain' => 'users', 'file' => 'users.md', 'count' => 12],
|
||||
['domain' => 'auth', 'file' => 'auth.md', 'count' => 15],
|
||||
];
|
||||
|
||||
$extensions = [
|
||||
['id' => 'sirsoft-page', 'type' => 'module', 'path' => '../../../modules/_bundled/sirsoft-page/docs/api/README.md', 'docs' => 2, 'endpoints' => 17],
|
||||
['id' => 'sirsoft-gdpr', 'type' => 'plugin', 'path' => '../../../plugins/_bundled/sirsoft-gdpr/docs/api/README.md', 'docs' => 4, 'endpoints' => 15],
|
||||
];
|
||||
|
||||
return [$entries, $extensions];
|
||||
}
|
||||
|
||||
/**
|
||||
* 코어 README 는 도메인 목차와 확장 API 목차를 함께 싣고, 재생성해도 멱등합니다.
|
||||
*
|
||||
* 최상위 README 의 "API 레퍼런스" 진입점이 이 문서이므로, 확장 API 문서의 발견 경로가
|
||||
* 여기 없으면 개발자/AI 가 확장 엔드포인트에 도달하지 못한다.
|
||||
*/
|
||||
#[Test]
|
||||
public function 코어_readme는_확장_목차를_함께_싣고_멱등하게_재생성된다(): void
|
||||
{
|
||||
$scaffolder = new ApiDocScaffolder;
|
||||
[$entries, $extensions] = $this->readmeFixtures();
|
||||
|
||||
$first = $scaffolder->readmeIndex('코어', $entries, null, $extensions);
|
||||
|
||||
$this->assertStringContainsString('## 확장 API 레퍼런스', $first);
|
||||
$this->assertStringContainsString('`sirsoft-page`', $first);
|
||||
$this->assertStringContainsString('`sirsoft-gdpr`', $first);
|
||||
$this->assertStringContainsString('**확장 수**: 2 · **엔드포인트 수**: 32', $first);
|
||||
|
||||
$second = $scaffolder->readmeIndex('코어', $entries, $first, $extensions);
|
||||
$this->assertSame($first, $second, '동일 입력 재생성은 멱등해야 한다.');
|
||||
$this->assertSame(1, substr_count($second, '## 확장 API 레퍼런스'), '확장 목차가 중복 생성되면 안 된다.');
|
||||
}
|
||||
|
||||
/**
|
||||
* 코어 README 상단의 사람 개요(공통 규약)는 재생성해도 보존됩니다.
|
||||
*
|
||||
* 개요는 목차 표보다 먼저 읽혀야 하므로 @generated 블록 앞에 둔다. 생성기가 이 구간을
|
||||
* 덮어쓰면 인증·응답 봉투·에러 규약 서술이 매 재생성마다 소실된다.
|
||||
*/
|
||||
#[Test]
|
||||
public function 코어_readme의_사람_개요는_생성_블록_앞에서_보존된다(): void
|
||||
{
|
||||
$scaffolder = new ApiDocScaffolder;
|
||||
[$entries, $extensions] = $this->readmeFixtures();
|
||||
|
||||
$base = $scaffolder->readmeIndex('코어', $entries, null, $extensions);
|
||||
$withOverview = str_replace(
|
||||
'<!-- @generated:start:api-readme-index -->',
|
||||
"## 공통 규약\n\nBearer 토큰 전용입니다. (사람 개요)\n\n<!-- @generated:start:api-readme-index -->",
|
||||
$base
|
||||
);
|
||||
|
||||
$regenerated = $scaffolder->readmeIndex('코어', $entries, $withOverview, $extensions);
|
||||
|
||||
$this->assertStringContainsString('Bearer 토큰 전용입니다. (사람 개요)', $regenerated);
|
||||
$this->assertSame(1, substr_count($regenerated, '## 공통 규약'), '개요가 중복 삽입되면 안 된다.');
|
||||
// 개요는 목차 표보다 앞에 있어야 한다.
|
||||
$this->assertLessThan(
|
||||
strpos($regenerated, '<!-- @generated:start:api-readme-index -->'),
|
||||
strpos($regenerated, '## 공통 규약')
|
||||
);
|
||||
|
||||
// 재생성 멱등 (개요 포함).
|
||||
$this->assertSame($regenerated, $scaffolder->readmeIndex('코어', $entries, $regenerated, $extensions));
|
||||
}
|
||||
|
||||
/**
|
||||
* 확장 스코프 실행이라 확장 목록을 넘기지 않아도 기존 확장 목차는 소실되지 않습니다.
|
||||
*
|
||||
* `--scope=core` 축소 실행이 코어 README 의 확장 표를 지워버리면, 매 실행마다 진입점이
|
||||
* 사라졌다 살아나는 drift 가 생긴다.
|
||||
*/
|
||||
#[Test]
|
||||
public function 확장_목록_미전달_시_기존_확장_목차를_보존한다(): void
|
||||
{
|
||||
$scaffolder = new ApiDocScaffolder;
|
||||
[$entries, $extensions] = $this->readmeFixtures();
|
||||
|
||||
$withExtensions = $scaffolder->readmeIndex('코어', $entries, null, $extensions);
|
||||
$regenerated = $scaffolder->readmeIndex('코어', $entries, $withExtensions, null);
|
||||
|
||||
$this->assertStringContainsString('## 확장 API 레퍼런스', $regenerated);
|
||||
$this->assertStringContainsString('`sirsoft-page`', $regenerated);
|
||||
$this->assertSame(1, substr_count($regenerated, '## 확장 API 레퍼런스'));
|
||||
}
|
||||
|
||||
/**
|
||||
* refreshExtensionIndex 는 코어 목차·개요를 건드리지 않고 확장 표만 갱신합니다.
|
||||
*
|
||||
* 확장 스코프 실행(`--scope=module:...`) 시 그 확장의 엔드포인트 수 변동을 코어 진입점에
|
||||
* 반영하는 경로다. 변경이 없으면 null 을 반환해 불필요한 파일 쓰기를 피한다.
|
||||
*/
|
||||
#[Test]
|
||||
public function 확장_목차만_in_place_갱신하고_변경_없으면_null을_반환한다(): void
|
||||
{
|
||||
$scaffolder = new ApiDocScaffolder;
|
||||
[$entries, $extensions] = $this->readmeFixtures();
|
||||
|
||||
$existing = $scaffolder->readmeIndex('코어', $entries, null, $extensions);
|
||||
|
||||
$this->assertNull(
|
||||
$scaffolder->refreshExtensionIndex($existing, $extensions),
|
||||
'동일 확장 목록이면 변경 없음(null)이어야 한다.'
|
||||
);
|
||||
|
||||
// 엔드포인트 수가 늘어난 경우 표만 갱신된다.
|
||||
$extensions[0]['endpoints'] = 20;
|
||||
$updated = $scaffolder->refreshExtensionIndex($existing, $extensions);
|
||||
|
||||
$this->assertNotNull($updated);
|
||||
$this->assertStringContainsString('2 / 20', $updated);
|
||||
// 코어 목차와 도메인 항목은 그대로 남는다.
|
||||
$this->assertStringContainsString('[users.md](users.md)', $updated);
|
||||
$this->assertStringContainsString('<!-- @generated:start:api-readme-index -->', $updated);
|
||||
$this->assertSame(1, substr_count($updated, '## 확장 API 레퍼런스'));
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user