mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 21:56:24 +00:00

- 5개 마이크로서비스 API 명세 작성 (User, Meeting, STT, AI, Notification)
- OpenAPI 3.0 표준 준수
- 총 47개 API 설계
- 유저스토리 100% 커버리지
- swagger-cli 검증 통과
- 종합 API 설계서 작성

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-23 10:49:29 +09:00

3.5 KiB

Raw Blame History

STT Service API 설계 완료

작업 결과

생성된 파일

파일 경로: C:\Users\KTDS\home\workspace\HGZero\design\backend\api\stt-service-api.yaml
형식: OpenAPI 3.0.3
검증 상태: ✅ 검증 완료 (swagger-cli)

API 개요

1. Recording API (음성 녹음 관리)

POST /recordings/prepare - 회의 녹음 준비
POST /recordings/{recordingId}/start - 음성 녹음 시작
POST /recordings/{recordingId}/stop - 음성 녹음 중지
GET /recordings/{recordingId} - 녹음 정보 조회

2. Transcription API (음성-텍스트 변환)

POST /transcripts/stream - 실시간 음성-텍스트 변환 (스트리밍)
POST /transcripts/batch - 배치 음성-텍스트 변환
POST /transcripts/callback - 배치 변환 완료 콜백
GET /transcripts/{recordingId} - 변환 텍스트 전체 조회

3. Speaker API (화자 식별 및 관리)

POST /speakers/identify - 화자 식별
GET /speakers/{speakerId} - 화자 정보 조회
PUT /speakers/{speakerId} - 화자 정보 업데이트
GET /recordings/{recordingId}/speakers - 녹음의 화자 목록 조회

주요 특징

1. 유저스토리 매핑

모든 API는 유저스토리와 매핑되어 있습니다:

UFR-STT-010 (음성녹음인식): Recording API, Speaker API
UFR-STT-020 (텍스트변환): Transcription API

2. 완전한 스키마 정의

25개의 스키마 정의
모든 Request/Response 모델 포함
Example 데이터 포함으로 Swagger UI에서 즉시 테스트 가능

3. Azure 통합

Azure Speech Service 연동
Azure Blob Storage 통합
Azure Event Hubs 이벤트 발행

4. 실시간 처리

WebSocket 기반 스트리밍 지원
실시간 인식 지연: < 1초
화자 식별 정확도: > 90%

5. 성능 정보

각 API의 예상 처리 시간 명시:

녹음 준비: ~1.1초
실시간 변환: 1-4초
배치 변환: 7-33초

API 확인 방법

1. Swagger Editor 사용

https://editor.swagger.io/ 접속
생성된 YAML 파일 내용 복사하여 붙여넣기
우측 패널에서 API 문서 확인 및 테스트

2. 로컬 Swagger UI 실행

# Swagger UI Docker 실행
docker run -p 8080:8080 -e SWAGGER_JSON=/api/stt-service-api.yaml \
  -v C:\Users\KTDS\home\workspace\HGZero\design\backend\api:/api \
  swaggerapi/swagger-ui

# 브라우저에서 http://localhost:8080 접속

3. VS Code Extension

확장: Swagger Viewer
YAML 파일 열고 Shift + Alt + P 실행
미리보기에서 API 문서 확인

설계 원칙 준수

✅ 유저스토리 기반 설계

모든 API에 x-user-story 필드 명시
불필요한 API 추가 없음

✅ 시퀀스 일관성

내부 시퀀스 설계와 완전히 일치
모든 처리 흐름 반영

✅ OpenAPI 3.0 표준

servers 섹션 필수 포함
완전한 스키마 정의
JWT 인증 방식 명시

✅ Example 데이터

모든 스키마에 example 포함
실제 테스트 가능한 데이터

✅ 검증 완료

swagger-cli 자동 검증 통과
YAML 구문 오류 없음
스키마 참조 유효성 확인

다음 단계

Meeting Service API 설계 (회의, 회의록, Todo 통합)
AI Service API 설계 (회의록 자동 작성, RAG 기능)
User Service API 설계 (인증 전용)
Notification Service API 설계 (알림 발송)

작성자: 준호 (Backend Developer) 작성일: 2025-01-23 검증 도구: swagger-cli v4.0.4

3.5 KiB Raw Blame History