Merge pull request #122 from InningLog/chore/#120/api-docs-pipeline

fix : 스냅샷 기반 diff로 신규/변경 엔드포인트만 문서 생성 #120

Author: GOOHAESEUNG

.github/workflows/deploy.yml

@@ -107,6 +107,21 @@ jobs:
           repository: InningLog/inninglog-api-docs
           token: ${{ secrets.DOCS_REPO_TOKEN }}
           path: docs-repo
+          fetch-depth: 0
+
+      - name: Restore previous auto-generated files
+        working-directory: docs-repo
+        run: |
+          BRANCH="auto/api-docs-update"
+          if git rev-parse --verify "origin/$BRANCH" >/dev/null 2>&1; then
+            git diff --name-only origin/main "origin/$BRANCH" | while IFS= read -r file; do
+              mkdir -p "$(dirname "$file")"
+              git show "origin/$BRANCH:$file" > "$file" 2>/dev/null || true
+            done
+            echo "Restored files from previous auto branch"
+          else
+            echo "No previous auto branch found"
+          fi
 
       - name: Run converter
         run: node scripts/openapi-to-gitbook/src/index.js -i openapi.json -o docs-repo

scripts/openapi-to-gitbook/src/converter.js

@@ -2,9 +2,39 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const { getDir } = require('./domainMapper');
-const { generateEndpointMarkdown, AUTO_MARKER } = require('./markdownGen');
-const { mergeSummary } = require('./summaryGen');
+const { generateEndpointMarkdown, AUTO_MARKER, resolveRef } = require('./markdownGen');
+const { scanAndMergeSummary } = require('./summaryGen');
+
+const SNAPSHOT_FILE = '.openapi-snapshot.json';
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+
+function collectRefs(obj, spec, depth, refs) {
+  if (!obj || typeof obj !== 'object' || depth > 3) return refs;
+
+  if (obj.$ref && !refs[obj.$ref]) {
+    const resolved = resolveRef(obj.$ref, spec);
+    if (resolved) {
+      refs[obj.$ref] = resolved;
+      collectRefs(resolved, spec, depth + 1, refs);
+    }
+  }
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) collectRefs(item, spec, depth, refs);
+  } else {
+    for (const val of Object.values(obj)) collectRefs(val, spec, depth, refs);
+  }
+
+  return refs;
+}
+
+function computeHash(operation, spec) {
+  const refs = collectRefs(operation, spec, 0, {});
+  const input = JSON.stringify({ operation, refs });
+  return crypto.createHash('md5').update(input).digest('hex');
+}
 
 function generateFileName(method, pathStr) {
   const segments = pathStr
@@ -17,18 +47,51 @@ function generateFileName(method, pathStr) {
 }
 
 function convert(spec, outputDir) {
-  const endpoints = [];
+  const snapshotPath = path.join(outputDir, SNAPSHOT_FILE);
+
+  // Load previous snapshot (endpoint hash map)
+  let prevHashes = null;
+  if (fs.existsSync(snapshotPath)) {
+    try {
+      prevHashes = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
+    } catch {
+      prevHashes = null;
+    }
+  }
+
+  // Build current hash map
+  const currentHashes = {};
+  for (const [pathStr, pathItem] of Object.entries(spec.paths || {})) {
+    for (const method of METHODS) {
+      if (!pathItem[method]) continue;
+      const key = `${method.toUpperCase()} ${pathStr}`;
+      currentHashes[key] = computeHash(pathItem[method], spec);
+    }
+  }
+
+  // First run: save baseline, generate nothing
+  if (!prevHashes) {
+    console.log('No previous snapshot found. Saving baseline snapshot.');
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(snapshotPath, JSON.stringify(currentHashes, null, 2), 'utf-8');
+    return { filesWritten: 0, skipped: 0, domains: 0 };
+  }
+
+  // Find new/changed endpoints
   let filesWritten = 0;
   let skipped = 0;
   const domainSet = new Set();
 
-  const methods = ['get', 'post', 'put', 'patch', 'delete'];
-
   for (const [pathStr, pathItem] of Object.entries(spec.paths || {})) {
-    for (const method of methods) {
+    for (const method of METHODS) {
       const operation = pathItem[method];
       if (!operation) continue;
 
+      const key = `${method.toUpperCase()} ${pathStr}`;
+
+      // Skip unchanged endpoints
+      if (prevHashes[key] === currentHashes[key]) continue;
+
       const tag = operation.tags?.[0] || '기타';
       const dir = getDir(tag);
       domainSet.add(dir);
@@ -50,17 +113,14 @@ function convert(spec, outputDir) {
       fs.mkdirSync(path.dirname(filePath), { recursive: true });
       fs.writeFileSync(filePath, markdown, 'utf-8');
       filesWritten++;
-
-      endpoints.push({
-        tag,
-        dir,
-        fileName,
-        title: operation.summary || `${method.toUpperCase()} ${pathStr}`,
-      });
     }
   }
 
-  mergeSummary(outputDir, endpoints);
+  // Save updated snapshot
+  fs.writeFileSync(snapshotPath, JSON.stringify(currentHashes, null, 2), 'utf-8');
+
+  // Scan all auto-generated files and merge SUMMARY.md
+  scanAndMergeSummary(outputDir);
 
   return { filesWritten, skipped, domains: domainSet.size };
 }

scripts/openapi-to-gitbook/src/markdownGen.js

@@ -263,4 +263,4 @@ function generateEndpointMarkdown(method, pathStr, operation, spec) {
   return lines.join('\n');
 }
 
-module.exports = { generateEndpointMarkdown, AUTO_MARKER };
+module.exports = { generateEndpointMarkdown, AUTO_MARKER, resolveRef };

scripts/openapi-to-gitbook/src/summaryGen.js

@@ -3,12 +3,47 @@
 const fs = require('fs');
 const path = require('path');
 const { getTagLabel } = require('./domainMapper');
+const { AUTO_MARKER } = require('./markdownGen');
 
 const START_MARKER = '<!-- AUTO-GENERATED-START -->';
 const END_MARKER = '<!-- AUTO-GENERATED-END -->';
 
+function scanAutoGeneratedFiles(outputDir) {
+  const endpoints = [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(outputDir, { withFileTypes: true });
+  } catch {
+    return endpoints;
+  }
+
+  const dirs = entries.filter(d => d.isDirectory()).map(d => d.name);
+
+  for (const dir of dirs) {
+    const dirPath = path.join(outputDir, dir);
+    let files;
+    try {
+      files = fs.readdirSync(dirPath).filter(f => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      const content = fs.readFileSync(path.join(dirPath, file), 'utf-8');
+      if (!content.startsWith(AUTO_MARKER)) continue;
+
+      const titleMatch = content.match(/^## (.+)$/m);
+      const title = titleMatch ? titleMatch[1] : file.replace('.md', '');
+
+      endpoints.push({ dir, fileName: file, title, tag: getTagLabel(dir) });
+    }
+  }
+
+  return endpoints;
+}
+
 function buildAutoSection(endpoints) {
-  // Group by domain directory
   const groups = {};
   for (const ep of endpoints) {
     if (!groups[ep.dir]) {
@@ -19,7 +54,6 @@ function buildAutoSection(endpoints) {
 
   const lines = [START_MARKER, ''];
 
-  // Sort domains alphabetically for consistency
   const sortedDirs = Object.keys(groups).sort();
   for (const dir of sortedDirs) {
     const group = groups[dir];
@@ -34,14 +68,14 @@ function buildAutoSection(endpoints) {
   return lines.join('\n');
 }
 
-function mergeSummary(outputDir, endpoints) {
+function scanAndMergeSummary(outputDir) {
+  const endpoints = scanAutoGeneratedFiles(outputDir);
   if (endpoints.length === 0) return;
 
   const summaryPath = path.join(outputDir, 'SUMMARY.md');
   const autoSection = buildAutoSection(endpoints);
 
   if (!fs.existsSync(summaryPath)) {
-    // No existing SUMMARY.md — create one with auto section
     const content = `# Table of contents\n\n* [소개](README.md)\n\n${autoSection}\n`;
     fs.writeFileSync(summaryPath, content, 'utf-8');
     return;
@@ -53,16 +87,14 @@ function mergeSummary(outputDir, endpoints) {
 
   let merged;
   if (startIdx !== -1 && endIdx !== -1) {
-    // Replace existing auto section
     const before = existing.substring(0, startIdx);
     const after = existing.substring(endIdx + END_MARKER.length);
     merged = before + autoSection + after;
   } else {
-    // Append auto section at the end
     merged = existing.trimEnd() + '\n\n' + autoSection + '\n';
   }
 
   fs.writeFileSync(summaryPath, merged, 'utf-8');
 }
 
-module.exports = { mergeSummary };
+module.exports = { scanAndMergeSummary };