mirror of
https://github.com/hwanny1128/HGZero.git
synced 2025-12-06 10:16:24 +00:00
## 주요 변경사항 ### 1. RAG Service 독립 서비스 문서화 - RAG Service OpenAPI 명세 작성 (9개 API) - Terms APIs: 용어 검색, 조회, 맥락 기반 설명 (3개) - Documents APIs: 관련 문서 검색, 통계 (2개) - Minutes APIs: 회의록 벡터 검색, 연관 검색 (4개) - 기술 스택: Python 3.11+, FastAPI, PostgreSQL+pgvector, Azure AI Search - 성능 요구사항 명시 (용어 검색 <500ms, 설명 생성 <3초) ### 2. 불필요한 설계서 삭제 (10개 파일, 27% 감소) - AI Service (3개): 결정사항제안, 논의사항제안, 회의록개선 - Meeting Service (5개): 실시간수정동기화, 충돌해결, Todo완료처리, Todo할당, 리마인더발송 - Notification Service (2개): Todo알림발송, 초대알림발송 ### 3. API 설계서 업데이트 (v2.0 → v2.1) - 마이크로서비스: 5개 → 6개 (RAG Service 추가) - 총 API 개수: 47개 → 56개 (+9개) - AI Service 주요 특징 업데이트 - RAG Service 연동 명시 - 삭제된 Suggestion API 제거 - 차별화 포인트: 맥락 기반 용어 설명, 하이브리드 검색 강조 - RAG Service 섹션 완전 신규 작성 - 통계 및 문서 이력 업데이트 ### 4. 내부 시퀀스 다이어그램 업데이트 (2개) - ai-전문용어감지.puml: RAG Service API 호출 방식 명시 - ai-맥락기반용어설명.puml: RAG Service API 호출 방식 명시 ### 5. 문서화 - 설계서 업데이트 요약 문서 작성 (claudedocs/설계서_업데이트_요약.md) - 전체 변경 사항, 영향 분석, 다음 단계 작업 명시 ## 영향 분석 - 설계서 파일: 37개 → 27개 (10개 삭제) - 유저스토리 커버리지: 28개 유저스토리 100% 반영 - 서비스 아키텍처: AI Service와 RAG Service 분리로 독립성 향상 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
532 lines
19 KiB
Markdown
532 lines
19 KiB
Markdown
# API 설계서
|
|
|
|
회의록 작성 및 공유 개선 서비스
|
|
|
|
---
|
|
|
|
## 📋 목차
|
|
|
|
1. [개요](#개요)
|
|
2. [API 설계 원칙](#api-설계-원칙)
|
|
3. [마이크로서비스별 API](#마이크로서비스별-api)
|
|
4. [공통 사항](#공통-사항)
|
|
5. [API 확인 방법](#api-확인-방법)
|
|
|
|
---
|
|
|
|
## 개요
|
|
|
|
### 프로젝트 정보
|
|
- **프로젝트명**: 회의록 작성 및 공유 개선 서비스
|
|
- **설계 버전**: v2.1
|
|
- **최종 수정일**: 2025-01-29
|
|
- **설계자**: 아키텍트(길동), Backend Developer(준호, 동욱)
|
|
|
|
### 마이크로서비스 구성
|
|
본 서비스는 6개의 마이크로서비스로 구성됩니다:
|
|
|
|
1. **User Service** - 사용자 인증 (LDAP 연동, JWT 토큰 발급/검증)
|
|
2. **Meeting Service** - 회의, 회의록, Todo, 실시간 협업 통합 관리
|
|
3. **STT Service** - 음성 녹음 관리, 음성-텍스트 변환, 화자 식별
|
|
4. **AI Service** - AI 기반 회의록 자동화, Todo 추출, RAG 서비스 연동
|
|
5. **RAG Service** - 용어집/관련자료/회의록 검색 (Python/FastAPI 독립 서비스)
|
|
6. **Notification Service** - 알림 발송 및 리마인더 관리
|
|
|
|
---
|
|
|
|
## API 설계 원칙
|
|
|
|
### 1. 설계 기준
|
|
- **유저스토리 기반**: 모든 API는 유저스토리와 매핑 (x-user-story 필드)
|
|
- **시퀀스 일치**: 외부/내부 시퀀스 설계서와 100% 일치
|
|
- **OpenAPI 3.0**: OpenAPI 3.0.3 표준 준수
|
|
- **컨트롤러 명시**: 각 API별 담당 컨트롤러 명시 (x-controller 필드)
|
|
|
|
### 2. 공통 표준
|
|
- **인증 방식**: JWT Bearer Token
|
|
- **요청 헤더**: 모든 API 요청에 사용자 정보 포함
|
|
- `X-User-Id`: 사용자 ID
|
|
- `X-User-Name`: 사용자 이름
|
|
- `X-User-Email`: 사용자 이메일
|
|
- **응답 형식**: JSON
|
|
- **에러 응답**: 표준화된 에러 응답 형식
|
|
|
|
### 3. 서비스 독립성
|
|
- **각 서비스별 독립적인 OpenAPI 명세**
|
|
- **서비스별 모든 스키마 포함**
|
|
- **중복 스키마 허용** (초기 단계)
|
|
- **독립 배포 가능**
|
|
|
|
---
|
|
|
|
## 마이크로서비스별 API
|
|
|
|
### 1. User Service
|
|
|
|
#### 개요
|
|
- **파일**: `user-service-api.yaml`
|
|
- **베이스 URL**: `/api/v1`
|
|
- **주요 기능**: 사용자 인증 전용 (LDAP 인증, JWT 토큰 관리)
|
|
|
|
#### API 목록
|
|
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /auth/login | 사용자 로그인 | AFR-USER-010 | UserController |
|
|
| POST | /auth/refresh | Access Token 갱신 | AFR-USER-010 | UserController |
|
|
| POST | /auth/logout | 로그아웃 | AFR-USER-010 | UserController |
|
|
| GET | /auth/validate | 토큰 검증 | AFR-USER-010 | UserController |
|
|
|
|
#### 주요 특징
|
|
- LDAP 인증 (LDAPS, port 636)
|
|
- JWT 토큰 관리 (Access: 1시간, Refresh: 7일)
|
|
- 계정 잠금 기능 (5회 실패 시 30분)
|
|
- Redis 기반 Refresh Token 관리
|
|
|
|
---
|
|
|
|
### 2. Meeting Service
|
|
|
|
#### 개요
|
|
- **파일**: `meeting-service-api.yaml`
|
|
- **베이스 URL**: `/api/v1`
|
|
- **주요 기능**: 회의, 회의록, Todo, 실시간 협업 통합 관리
|
|
|
|
#### API 목록
|
|
|
|
**Dashboard APIs (1개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /dashboard | 대시보드 데이터 조회 | AFR-USER-020 | DashboardController |
|
|
|
|
**Meeting APIs (4개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /meetings | 회의 예약 | UFR-MEET-010 | MeetingController |
|
|
| PUT | /meetings/{meetingId}/template | 템플릿 선택 | UFR-MEET-020 | MeetingController |
|
|
| POST | /meetings/{meetingId}/start | 회의 시작 | UFR-MEET-030 | MeetingController |
|
|
| POST | /meetings/{meetingId}/end | 회의 종료 | UFR-MEET-040 | MeetingController |
|
|
|
|
**Minutes APIs (7개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /minutes | 회의록 목록 조회 | UFR-MEET-046 | MinutesController |
|
|
| GET | /minutes/{minutesId} | 회의록 상세 조회 | UFR-MEET-047 | MinutesController |
|
|
| PATCH | /minutes/{minutesId} | 회의록 수정 | UFR-MEET-055 | MinutesController |
|
|
| POST | /minutes/{minutesId}/finalize | 회의록 확정 | UFR-MEET-050 | MinutesController |
|
|
| POST | /minutes/{minutesId}/sections/{sectionId}/verify | 섹션 검증 완료 | UFR-COLLAB-030 | MinutesController |
|
|
| POST | /minutes/{minutesId}/sections/{sectionId}/lock | 섹션 잠금 | UFR-COLLAB-030 | MinutesController |
|
|
| DELETE | /minutes/{minutesId}/sections/{sectionId}/lock | 섹션 잠금 해제 | UFR-COLLAB-030 | MinutesController |
|
|
|
|
**Todo APIs (2개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /todos | Todo 할당 | UFR-TODO-010 | TodoController |
|
|
| PATCH | /todos/{todoId}/complete | Todo 완료 처리 | UFR-TODO-030 | TodoController |
|
|
|
|
**Template APIs (2개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /templates | 템플릿 목록 조회 | UFR-MEET-020 | TemplateController |
|
|
| GET | /templates/{templateId} | 템플릿 상세 조회 | UFR-MEET-020 | TemplateController |
|
|
|
|
**WebSocket Endpoints (1개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /ws/minutes/{minutesId} | 실시간 협업 WebSocket | UFR-COLLAB-010 | WebSocketController |
|
|
|
|
#### 주요 특징
|
|
- WebSocket 기반 실시간 협업
|
|
- 충돌 해결 메커니즘 (Last Write Wins)
|
|
- 섹션별 검증 및 잠금 기능
|
|
- Todo와 회의록 양방향 연결
|
|
- 버전 관리
|
|
|
|
---
|
|
|
|
### 3. STT Service
|
|
|
|
#### 개요
|
|
- **파일**: `stt-service-api.yaml`
|
|
- **베이스 URL**: `/api/v1`
|
|
- **주요 기능**: 음성 녹음 관리, 음성-텍스트 변환, 화자 식별
|
|
|
|
#### API 목록
|
|
|
|
**Recording APIs (4개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /recordings/prepare | 녹음 준비 | UFR-STT-010 | RecordingController |
|
|
| POST | /recordings/{recordingId}/start | 녹음 시작 | UFR-STT-010 | RecordingController |
|
|
| POST | /recordings/{recordingId}/stop | 녹음 중지 | UFR-STT-010 | RecordingController |
|
|
| GET | /recordings/{recordingId} | 녹음 정보 조회 | UFR-STT-010 | RecordingController |
|
|
|
|
**Transcription APIs (4개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /transcriptions/stream | 실시간 스트리밍 변환 | UFR-STT-020 | TranscriptionController |
|
|
| POST | /transcriptions/batch | 배치 변환 | UFR-STT-020 | TranscriptionController |
|
|
| POST | /transcriptions/callback | 변환 완료 콜백 | UFR-STT-020 | TranscriptionController |
|
|
| GET | /transcriptions/{recordingId}/full | 전체 텍스트 조회 | UFR-STT-020 | TranscriptionController |
|
|
|
|
**Speaker APIs (4개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /speakers/identify | 화자 식별 | UFR-STT-010 | SpeakerController |
|
|
| GET | /speakers/{speakerId} | 화자 정보 조회 | UFR-STT-010 | SpeakerController |
|
|
| PATCH | /speakers/{speakerId} | 화자 정보 수정 | UFR-STT-010 | SpeakerController |
|
|
| GET | /recordings/{recordingId}/speakers | 녹음별 화자 목록 | UFR-STT-010 | SpeakerController |
|
|
|
|
#### 주요 특징
|
|
- WebSocket 기반 실시간 스트리밍 (< 1초 지연)
|
|
- 화자 식별 정확도 90% 이상
|
|
- Azure Speech Service 통합
|
|
- Azure Blob Storage 연동
|
|
- Azure Event Hubs 비동기 처리
|
|
|
|
---
|
|
|
|
### 4. AI Service
|
|
|
|
#### 개요
|
|
- **파일**: `ai-service-api.yaml`
|
|
- **베이스 URL**: `/api/v1`
|
|
- **주요 기능**: AI 기반 회의록 자동화, Todo 추출, 지능형 검색 (RAG 통합)
|
|
|
|
#### API 목록
|
|
|
|
**Transcript Processing APIs (1개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /transcripts/process | 회의록 자동 작성 | UFR-AI-010 | TranscriptController |
|
|
|
|
**Todo APIs (1개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /todos/extract | Todo 자동 추출 | UFR-AI-020 | TodoController |
|
|
|
|
**Summary APIs (2개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /sections/{sectionId}/summary | 안건별 AI 요약 생성 | UFR-AI-010 | SectionController |
|
|
| POST | /sections/{sectionId}/regenerate | 한줄 요약 재생성 | UFR-AI-036 | SectionController |
|
|
|
|
**Suggestion APIs (1개) - 실시간 AI 제안**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /meetings/{meetingId}/suggestions/stream | 실시간 주요 내용 제안 (SSE) | UFR-AI-030 | SuggestionController |
|
|
|
|
**Related Transcripts APIs (1개) - RAG 연동**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /transcripts/{meetingId}/related | 관련 회의록 검색 (RAG 서비스 연동) | UFR-AI-040 | RelatedTranscriptController |
|
|
|
|
**Term APIs (2개) - RAG 연동**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /terms/detect | 전문용어 감지 (RAG 서비스 연동) | UFR-RAG-010 | TermController |
|
|
| GET | /terms/{termId}/explain | 맥락 기반 용어 설명 (RAG 서비스 연동) | UFR-RAG-020 | ExplanationController |
|
|
|
|
#### 주요 특징
|
|
- LLM 기반 회의록 자동 작성 (Claude 3.5 Sonnet)
|
|
- RAG Service 연동
|
|
- 전문용어 자동 감지 및 맥락 기반 설명
|
|
- 관련 회의록 검색 (벡터 유사도 70% 이상)
|
|
- 조직 내 문서 및 이력 기반 용어 설명 생성
|
|
- 안건별 요약 생성 (한줄 요약 + 상세 요약)
|
|
- 실시간 주요 내용 제안 (SSE 스트리밍)
|
|
- Todo 자동 추출 (Meeting Service에 전달)
|
|
|
|
#### 차별화 포인트
|
|
1. **맥락 기반 용어 설명**: 단순 사전 정의가 아닌, RAG를 통해 조직 내 실제 사용 맥락과 과거 논의 이력 제공
|
|
2. **하이브리드 검색 기반 연관성**: 키워드 매칭과 벡터 유사도를 결합하여 관련 회의록 정확도 향상
|
|
3. **실시간 AI 제안**: SSE 기반 스트리밍으로 회의 중 주요 내용 실시간 제안
|
|
|
|
---
|
|
|
|
### 5. RAG Service
|
|
|
|
#### 개요
|
|
- **파일**: `rag-service-api.yaml`
|
|
- **베이스 URL**: `/api/rag`
|
|
- **주요 기능**: 용어집 검색, 관련자료 검색, 회의록 유사도 검색
|
|
- **기술 스택**: Python 3.11+, FastAPI, PostgreSQL+pgvector, Azure AI Search, Redis
|
|
|
|
#### API 목록
|
|
|
|
**Terms APIs (3개) - 용어집 검색**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /terms/search | 용어 검색 (Hybrid: Keyword + Vector) | UFR-RAG-010 | TermsController |
|
|
| GET | /terms/{termId} | 용어 상세 조회 | UFR-RAG-010 | TermsController |
|
|
| POST | /terms/{termId}/explain | 맥락 기반 용어 설명 (Claude AI) | UFR-RAG-020 | TermsController |
|
|
|
|
**Documents APIs (2개) - 관련자료 검색**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /documents/search | 관련 문서 검색 (Hybrid Search + Semantic Ranking) | UFR-RAG-030 | DocumentsController |
|
|
| GET | /documents/stats | 문서 통계 조회 | - | DocumentsController |
|
|
|
|
**Minutes APIs (4개) - 회의록 유사도 검색**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /minutes/search | 회의록 벡터 검색 | UFR-RAG-030 | MinutesController |
|
|
| GET | /minutes/{minutesId} | 회의록 상세 조회 | UFR-RAG-030 | MinutesController |
|
|
| POST | /minutes/related | 연관 회의록 조회 (벡터 유사도) | UFR-RAG-030 | MinutesController |
|
|
| GET | /minutes/stats | 회의록 통계 조회 | - | MinutesController |
|
|
|
|
#### 주요 특징
|
|
- **하이브리드 검색**: 키워드 검색 + 벡터 유사도 검색 (가중치 기반 통합)
|
|
- **임베딩 모델**: Azure OpenAI text-embedding-3-large (3,072 차원)
|
|
- **LLM**: Claude 3.5 Sonnet (맥락 기반 설명 생성)
|
|
- **캐싱**: Redis 기반 결과 캐싱 (TTL: 30분~1시간)
|
|
- **EventHub 연동**: Meeting 서비스에서 회의록 확정 이벤트 수신 → 벡터 DB 저장
|
|
|
|
#### 데이터베이스
|
|
- **PostgreSQL + pgvector**: 용어집 저장 및 벡터 검색
|
|
- **Azure AI Search**: 관련자료 하이브리드 검색 + Semantic Ranking
|
|
- **벡터 유사도**: Cosine Similarity (임계값 70% 이상)
|
|
|
|
#### 성능 요구사항
|
|
- **용어 검색**: < 500ms (캐시 HIT 시 < 50ms)
|
|
- **용어 설명 생성**: < 3초 (Claude API 호출 포함)
|
|
- **회의록 검색**: < 1초 (캐시 HIT 시 < 100ms)
|
|
|
|
---
|
|
|
|
### 6. Notification Service
|
|
|
|
#### 개요
|
|
- **파일**: `notification-service-api.yaml`
|
|
- **베이스 URL**: `/api/v1`
|
|
- **주요 기능**: 알림 발송 및 리마인더 관리
|
|
|
|
#### API 목록
|
|
|
|
**Internal APIs (2개) - 이벤트 핸들러**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| POST | /notifications/invitation | 회의 초대 알림 발송 | UFR-MEET-010 | NotificationController |
|
|
| POST | /notifications/todo | Todo 할당 알림 발송 | UFR-TODO-010 | NotificationController |
|
|
|
|
**Public APIs (2개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /notifications | 사용자별 알림 이력 조회 | AFR-USER-020 | NotificationController |
|
|
| GET | /notifications/{notificationId} | 알림 상세 조회 | AFR-USER-020 | NotificationController |
|
|
|
|
**Settings APIs (2개)**
|
|
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|
|
|--------|----------|------|-----------|----------|
|
|
| GET | /notifications/settings | 알림 설정 조회 | AFR-USER-020 | NotificationSettingsController |
|
|
| PUT | /notifications/settings | 알림 설정 업데이트 | AFR-USER-020 | NotificationSettingsController |
|
|
|
|
#### 주요 특징
|
|
- Azure Event Hubs 기반 비동기 처리
|
|
- 이메일 템플릿 렌더링
|
|
- 중복 발송 방지 (Idempotency)
|
|
- 재시도 메커니즘 (최대 3회, exponential backoff)
|
|
- 알림 설정 관리 (채널, 유형, 방해 금지 시간대)
|
|
|
|
#### 이메일 템플릿
|
|
- **회의 초대**: 회의 정보 + 참여 링크 + 캘린더 추가
|
|
- **Todo 할당**: Todo 상세 + 회의록 링크
|
|
- **리마인더**: 회의 시작 30분 전 자동 발송
|
|
- **Todo 리마인더**: 마감일 3일 전, 1일 전, 당일
|
|
|
|
---
|
|
|
|
## 공통 사항
|
|
|
|
### 인증 및 권한
|
|
|
|
#### JWT 토큰 구조
|
|
```json
|
|
{
|
|
"userId": "string",
|
|
"userName": "string",
|
|
"email": "string",
|
|
"exp": 1234567890
|
|
}
|
|
```
|
|
|
|
#### 인증 헤더
|
|
```
|
|
Authorization: Bearer {access_token}
|
|
```
|
|
|
|
#### 사용자 정보 헤더 (모든 API 요청)
|
|
```
|
|
X-User-Id: {userId}
|
|
X-User-Name: {userName}
|
|
X-User-Email: {userEmail}
|
|
```
|
|
|
|
### 에러 응답 형식
|
|
|
|
#### 공통 에러 응답
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"code": "ERROR_CODE",
|
|
"message": "에러 메시지",
|
|
"details": {
|
|
"field": "필드명",
|
|
"reason": "상세 사유"
|
|
},
|
|
"timestamp": "2025-01-23T10:00:00Z"
|
|
}
|
|
```
|
|
|
|
#### HTTP 상태 코드
|
|
- **200**: 성공
|
|
- **201**: 생성 성공
|
|
- **400**: 잘못된 요청
|
|
- **401**: 인증 실패
|
|
- **403**: 권한 없음
|
|
- **404**: 리소스 없음
|
|
- **409**: 충돌 (동시 수정 등)
|
|
- **500**: 서버 오류
|
|
|
|
### 페이징 표준
|
|
|
|
#### 요청 파라미터
|
|
```
|
|
page: 페이지 번호 (default: 0)
|
|
size: 페이지 크기 (default: 20, max: 100)
|
|
sort: 정렬 기준 (예: createdAt,desc)
|
|
```
|
|
|
|
#### 응답 형식
|
|
```json
|
|
{
|
|
"content": [...],
|
|
"pageable": {
|
|
"page": 0,
|
|
"size": 20,
|
|
"totalElements": 100,
|
|
"totalPages": 5
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## API 확인 방법
|
|
|
|
### 1. Swagger Editor에서 확인
|
|
|
|
1. **Swagger Editor 접속**
|
|
- https://editor.swagger.io/
|
|
|
|
2. **각 서비스 YAML 파일 확인**
|
|
- `design/backend/api/spec/user-service-api.yaml`
|
|
- `design/backend/api/spec/meeting-service-api.yaml`
|
|
- `design/backend/api/spec/stt-service-api.yaml`
|
|
- `design/backend/api/spec/ai-service-api.yaml`
|
|
- `design/backend/api/spec/rag-service-api.yaml`
|
|
- `design/backend/api/spec/notification-service-api.yaml`
|
|
|
|
3. **파일 내용 붙여넣기**
|
|
- 좌측 패널에 YAML 내용 붙여넣기
|
|
- 우측 패널에서 API 문서 확인
|
|
|
|
4. **API 테스트**
|
|
- "Try it out" 버튼으로 API 테스트
|
|
- Example 데이터로 요청/응답 시뮬레이션
|
|
|
|
### 2. 로컬에서 검증
|
|
|
|
#### swagger-cli 설치
|
|
```bash
|
|
npm install -g @apidevtools/swagger-cli
|
|
```
|
|
|
|
#### 검증 실행
|
|
```bash
|
|
# 개별 파일 검증
|
|
swagger-cli validate design/backend/api/spec/user-service-api.yaml
|
|
|
|
# 전체 파일 검증
|
|
swagger-cli validate design/backend/api/spec/*.yaml
|
|
```
|
|
|
|
#### 검증 결과
|
|
```
|
|
design/backend/api/spec/user-service-api.yaml is valid
|
|
design/backend/api/spec/meeting-service-api.yaml is valid
|
|
design/backend/api/spec/stt-service-api.yaml is valid
|
|
design/backend/api/spec/ai-service-api.yaml is valid
|
|
design/backend/api/spec/rag-service-api.yaml is valid
|
|
design/backend/api/spec/notification-service-api.yaml is valid
|
|
```
|
|
|
|
---
|
|
|
|
## 통계
|
|
|
|
### API 개수 요약
|
|
|
|
| 서비스 | API 개수 | 주요 기능 |
|
|
|--------|---------|----------|
|
|
| User Service | 4 | 사용자 인증 |
|
|
| Meeting Service | 17 | 회의, 회의록, Todo 관리 |
|
|
| STT Service | 12 | 음성 녹음, 변환, 화자 식별 |
|
|
| AI Service | 8 | AI 회의록, Todo 추출, RAG 연동 |
|
|
| RAG Service | 9 | 용어집/문서/회의록 검색 |
|
|
| Notification Service | 6 | 알림 발송, 설정 관리 |
|
|
| **합계** | **56** | |
|
|
|
|
### 유저스토리 커버리지
|
|
|
|
- **전체 유저스토리**: 28개
|
|
- **API로 구현된 유저스토리**: 28개
|
|
- **커버리지**: 100%
|
|
|
|
---
|
|
|
|
## 문서 이력
|
|
|
|
| 버전 | 작성일 | 작성자 | 변경 내용 |
|
|
|------|--------|--------|----------|
|
|
| 1.0 | 2025-01-23 | 길동 (아키텍트), 준호 (Backend Developer) | 초안 작성 (5개 마이크로서비스) |
|
|
| 2.0 | 2025-01-25 | 준호 (Backend Developer) | Todo 관리 기능 추가, 실시간 협업 설계 |
|
|
| 2.1 | 2025-01-29 | 동욱 (Backend Developer) | RAG Service 추가, 불필요한 API 정리 (6개 마이크로서비스) |
|
|
|
|
---
|
|
|
|
## 부록
|
|
|
|
### A. 참조 문서
|
|
- 유저스토리: `design/userstory.md`
|
|
- 외부 시퀀스 설계서: `design/backend/sequence/outer/*.puml`
|
|
- 내부 시퀀스 설계서: `design/backend/sequence/inner/*.puml`
|
|
- 공통 설계 원칙: `claude/common-principles.md`
|
|
- API 설계 가이드: `claude/api-design.md`
|
|
|
|
### B. 파일 구조
|
|
```
|
|
design/backend/api/
|
|
├── user-service-api.yaml # User Service API 명세
|
|
├── meeting-service-api.yaml # Meeting Service API 명세
|
|
├── stt-service-api.yaml # STT Service API 명세
|
|
├── ai-service-api.yaml # AI Service API 명세
|
|
├── notification-service-api.yaml # Notification Service API 명세
|
|
└── API설계서.md # 본 문서
|
|
```
|
|
|
|
### C. OpenAPI 3.0 주요 섹션
|
|
- **openapi**: 버전 정보 (3.0.3)
|
|
- **info**: API 메타데이터
|
|
- **servers**: 서버 URL
|
|
- **paths**: API 엔드포인트
|
|
- **components**: 재사용 가능한 컴포넌트
|
|
- schemas: 데이터 모델
|
|
- parameters: 공통 파라미터
|
|
- responses: 공통 응답
|
|
- securitySchemes: 인증 방식
|
|
|
|
---
|
|
|
|
**© 2025 회의록 작성 및 공유 개선 서비스. All rights reserved.**
|