This commit is contained in:
dahyeon committed 2025-11-14 14:57:34 +00:00
1 parent 04fccbb539
commit 214469eb31
31 files changed
+2345 -708

No files matched your search

+138
View File
@@ -0,0 +1,138 @@
# API Integration Summary
## Overview
Successfully integrated the frontend SPA with the backend API server using Kiota API client and React Query for data fetching and state management.
## Changes Made
### 1. API Client Setup
- **File**: `src/lib/apiClient.ts`
- Created a centralized API client using Kiota's `DefaultRequestAdapter`
- Configured with `AnonymousAuthenticationProvider` for now (can be upgraded to authenticated requests later)
- Base URL configured to: `https://moeum.dahyeon.us/`
### 2. React Query Hooks
- **File**: `src/hooks/useApi.ts`
- Created custom hooks for API calls:
- `useSiteHeader()` - Fetches site header navigation data
- `useTaxonomyChildren(taxonomyId)` - Fetches child items for a taxonomy
- `useArticle(slug)` - Fetches article content by slug
- `useArticleTaxonomyPath(slug)` - Fetches taxonomy path for an article
### 3. React Query Provider
- **File**: `src/main.tsx`
- Added `QueryClientProvider` to wrap the app
- Configured with:
- 5-minute stale time
- Disabled refetch on window focus
### 4. Header Component Updates
- **File**: `src/components/Header.tsx`
- Replaced hardcoded menu items with dynamic data from `getSiteHeader` API
- Menu structure mapping:
- API `label` → Menu button label (e.g., "Documentation", "Training")
- API `key` → Internal identifier for menu state
- API `sections[].headline` → Dropdown section headers (e.g., "DOCUMENTATION")
- API `sections[].taxonomies[].label` → Dropdown menu items
- API `sections[].taxonomies[].taxonomyId` → Click handler for navigation
- Added `onTaxonomyClick` prop to handle taxonomy navigation
### 5. Sidebar Component Updates
- **File**: `src/components/Sidebar.tsx`
- Replaced hardcoded navigation with dynamic taxonomy child items
- Fetches data from `/v1/taxonomies/{id}/child-items` endpoint
- Recursive rendering of nested menu items
- Mapping:
- API `items[].title` → Menu item label
- API `items[].href` → Article slug for navigation
- API `items[].children` → Nested submenu items
- Added `onArticleClick` prop to handle article selection
### 6. MainContent Component Updates
- **File**: `src/components/MainContent.tsx`
- Replaced hardcoded article content with dynamic data from API
- Fetches data from `/v1/articles/{slug}` endpoint
- Displays:
- Article title
- Last updated date
- Article content (rendered as HTML)
- Added loading and error states
- Shows placeholder message when no article is selected
### 7. App State Management
- **File**: `src/App.tsx`
- Added state for:
- `currentTaxonomyId` - Tracks selected taxonomy
- `currentArticleSlug` - Tracks selected article
- Added handlers:
- `handleTaxonomyClick` - Navigates to documentation page and loads taxonomy
- `handleArticleClick` - Loads article content
- Props flow: App → DocumentationPage → Sidebar/MainContent
### 8. DocumentationPage Updates
- **File**: `src/components/DocumentationPage.tsx`
- Updated to accept and pass through:
- `taxonomyId` → Sidebar
- `articleSlug` → MainContent
- `onArticleClick` → Sidebar
## Data Flow
```
1. User clicks menu item in Header
↓
2. Header calls onTaxonomyClick(taxonomyId)
↓
3. App updates currentTaxonomyId state
↓
4. Sidebar fetches /v1/taxonomies/{id}/child-items
↓
5. User clicks article in Sidebar
↓
6. Sidebar calls onArticleClick(slug)
↓
7. App updates currentArticleSlug state
↓
8. MainContent fetches /v1/articles/{slug}
↓
9. Article content is displayed
```
## API Endpoints Used
1. **GET /v1/contents/site-header**
- Returns array of site header configurations
- Used by: Header component
2. **GET /v1/taxonomies/{id}/child-items**
- Returns hierarchical menu structure for a taxonomy
- Used by: Sidebar component
3. **GET /v1/articles/{slug}**
- Returns article content and metadata
- Used by: MainContent component
4. **GET /v1/articles/{slug}/taxonomy-path** (prepared but not yet used)
- Returns taxonomy path for breadcrumb navigation
- Can be used for enhanced breadcrumb display
## Dependencies Added
- `@tanstack/react-query@^5.90.8` - Already in package.json
- `@microsoft/kiota-bundle@^1.0.0-preview.99` - Already in package.json
- `@types/react-dom` - Added for TypeScript support
## Testing
The application is now running at `http://localhost:3420` and ready for testing with your API server.
## Next Steps (Optional Enhancements)
1. **Authentication**: Replace `AnonymousAuthenticationProvider` with proper auth
2. **Error Handling**: Add more detailed error messages and retry logic
3. **Caching**: Fine-tune React Query cache settings based on data update frequency
4. **Breadcrumbs**: Use `useArticleTaxonomyPath` to show full navigation path
5. **Search**: Implement search functionality using the search input in Sidebar
6. **Loading Skeletons**: Replace simple loading text with skeleton screens
7. **Optimistic Updates**: Add optimistic UI updates for better UX
8. **Offline Support**: Add service worker for offline article reading