API Doc 포트폴리오

Source: Dev.to

번역을 진행하려면 번역이 필요한 전체 텍스트를 제공해 주시겠어요? 현재는 소스 링크만 포함되어 있어 번역할 내용이 없습니다. 텍스트를 알려주시면 바로 한국어로 번역해 드리겠습니다.

Overview

My hack‑athon goal was to craft a portfolio that stands out while remaining approachable.
I chose an API‑documentation aesthetic (think Swagger / Postman) to reflect my developer identity, yet I kept the experience friendly for non‑technical visitors.

• Single‑source data: All personal information lives in one data.json file, making updates painless.
• Tech stack: React + TypeScript for scalability & type safety, Tailwind CSS for rapid, consistent UI design.
• Tools used:
  • Gemini – creative prompt‑engineering assistant.
  • Antigravity IDE (Gemini 3 Pro) – senior‑frontend reviewer, refactoring, bug‑fixing, UI/UX feedback.
  • Google Cloud Run – deployment platform.

I followed Google scientists’ prompt‑engineering guide, applying one‑shot, step‑back, and tree‑of‑thought techniques. Selected prompts are included below.

Source: …

Prompt 1 – 이력서 페이지를 JSON에서 데이터 가져오도록 리팩터링

컨텍스트:
우리는 데이터‑드리븐 아키텍처로 전환하고 있습니다. 모든 콘텐츠는 이제 data.json에 저장됩니다.

작업:
“Resume/IDE Viewer” 페이지(HTML/JS)를 리팩터링하여 data.json에서 동적으로 내용을 로드하도록 합니다.

요구 사항

1. JSON 구조 (정확한 형태)

   {
     "resume": {
       "pdf_path": "/assets/cv.pdf",
       "filename": "cv_xxx_backend.pdf",
       "last_updated": "2026-01-12",
       "raw_data": {
         "name": "XXX",
         "role": "Junior Backend Developer",
         "stack": ["Python", "Django", "Docker"]
       }
     }
   }

2. TypeScript 로직 (Fetch & DOM 조작)

   • 페이지 로드 시: fetch('./data.json').
   • PDF 업데이트: <iframe>(또는 유사 요소)를 찾아 src를 resume.pdf_path로 설정.
   • “Raw” 뷰 업데이트: “Raw (JSON)” 탭의 코드 블록에 resume.raw_data를 보기 좋게 포맷해서 채움.
   • UI 라벨 업데이트: breadcrumb/파일‑경로 라벨을 resume.filename으로 변경.

3. HTML 변경

   • PDF 컨테이너에 하드코딩된 src를 제거하고(빈 상태 또는 로딩 스피너 표시).
   • JS 타깃팅을 위한 고유 ID 추가, 예:
     • id="pdf-viewer"
     • id="json-code-block"
     • id="file-name-label"

전달물

아래는 최소 HTML 스니펫과 업데이트된 JavaScript(TypeScript 호환)이며, 위 요구 사항을 만족합니다.

HTML (발췌)

<!-- PDF viewer -->
<iframe id="pdf-viewer" src=""></iframe>

<!-- Tabs -->
<button id="preview-tab">Preview</button>
<button id="raw-tab">Raw (JSON)</button>

<!-- JSON code block -->
<pre id="json-code-block"></pre>

<!-- Breadcrumb / filename label -->
<span id="file-name-label"></span>

JavaScript / TypeScript (ES6)

// src/utils/loadResume.ts
interface ResumeRaw {
  name: string;
  role: string;
  stack: string[];
}

interface ResumeData {
  pdf_path: string;
  filename: string;
  last_updated: string;
  raw_data: ResumeRaw;
}

interface PortfolioJSON {
  resume: ResumeData;
}

/**
 * Fetches `data.json`, updates the DOM, and handles errors.
 */
async function initResumeViewer(): Promise<void> {
  try {
    const response = await fetch('./data.json');
    if (!response.ok) throw new Error(`HTTP ${response.status}`);

    const data: PortfolioJSON = await response.json();
    const { pdf_path, filename, raw_data } = data.resume;

    // ---- Update PDF viewer ----
    const pdfViewer = document.getElementById('pdf-viewer') as HTMLIFrameElement;
    if (pdfViewer) pdfViewer.src = pdf_path;

    // ---- Update filename breadcrumb ----
    const fileLabel = document.getElementById('file-name-label');
    if (fileLabel) fileLabel.textContent = filename;

    // ---- Populate Raw JSON view ----
    const jsonBlock = document.getElementById('json-code-block');
    if (jsonBlock) {
      const pretty = JSON.stringify(raw_data, null, 2);
      jsonBlock.textContent = pretty;
    }
  } catch (err) {
    console.error('Failed to load resume data:', err);
    // Optional: display a user‑friendly fallback UI
  }
}

// Run on DOM ready
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', initResumeViewer);
} else {
  initResumeViewer();
}

Prompt 2 – UX Audit for Non‑Technical Users (Recruiter Persona)

Role: Senior UX Researcher paired with a Non‑Technical Tech Recruiter (HR Manager).

Context:
The portfolio uses a heavy API‑Documentation / CLI theme: dark mode, monospaced fonts, terminal‑style inputs, JSON code blocks, sidebar navigation (Stripe‑Docs style), and a command palette.

Problem:
The design may be over‑engineered, potentially confusing recruiters who lack coding experience, increasing cognitive load and navigation friction.

Heuristic Evaluation

Specific Questions Answered

Summary

• Maintain the technical aesthetic (dark theme, code‑like borders, line numbers) while simplifying interactions for non‑technical users.
• Prioritize readability: plain text for bios, bullet points for experience, high‑contrast colors.
• Offer progressive disclosure: advanced JSON or terminal features are hidden behind optional toggles, keeping the primary experience clean and approachable.

es는 선택적 토글 뒤에 숨겨져 있어 기본 흐름을 간단하게 유지합니다.

Implementing these bridges will let recruiters find the essential information (Name, Role, Tech Stack, Resume) within the 6‑second scan window while preserving the unique API‑documentation personality of the portfolio.

I’m proud of how this project turned the portfolio itself into an experiment. Instead of focusing only on visuals, I treated it as a system: maintainable, extensible, and driven by data. Designing the entire site around a single JSON source allowed me to iterate quickly and keep the structure clean throughout the hackathon.

I’m also especially proud of how I used AI as a collaborator rather than just a code generator. By refining prompts and applying techniques, I was able to use Gemini and Antigravity Agents as creative and technical reviewers, helping me improve architecture decisions, UI/UX, and overall clarity.