콘텐츠로 이동

API 레퍼런스

백엔드 REST API의 단일 출처. 컨트롤러 테스트가 통과하는 endpoint만 자동으로 명세에 포함되므로, 본 페이지는 코드와 절대 drift하지 않는다.

구성

페이지 내용
OpenAPI 스펙 자동 생성된 OpenAPI 3 명세 (34 endpoints, 56 schemas) — 페이지에서 endpoint별 검색 가능

자동 생성 흐름

컨트롤러 변경 → CI 트리거 → ./gradlew test openapi3 (restdocs-api-spec)
       ↓
docs/wiki/api/openapi.yaml auto-commit (GitHub Actions, [skip ci])
       ↓
Cloudflare Pages 새 commit 감지 → mkdocs build → 재배포
       ↓
wiki.semugpt.co.kr/04-api-reference/openapi/ 에 반영

새 endpoint 추가 시 별도 wiki 작업 없이 자동 반영 — 단, 컨트롤러 테스트(@WebMvcTest + document(...))가 있어야 한다. 테스트가 없는 endpoint는 OpenAPI에 누락된다.

Schema 명명 컨벤션

document(identifier, ...) 호출의 identifier를 정규화하여 schema 이름 자동 생성:

  • phone-authentication-issue-normal → PhoneAuthenticationIssueRequest / PhoneAuthenticationIssueResponse
  • phone-authentication-issue-error-send → 동일 schema 공유 (case suffix 제거)

case 접미사 인식 패턴: -normal, -error-*, -not-found, -not-exists, -invalid-*, -without-*, -token-exceeded. 같은 endpoint의 happy/error 케이스가 단일 schema를 공유한다.

자세한 helper 동작은 apps/backend/src/test/kotlin/me/uiti/taxgpt/common/RestDocsUtil.kt 참조.

외부 시스템 API (참고)

본 페이지는 백엔드 자체 API만 다룬다. 외부 시스템 API는 각 기능 페이지에서:

외부 API 위치
Toss Payments (/v1/payments/confirm, /v1/billing/{billingKey}) 결제
Naver Cloud SENS SMS 회원 / 인증
OpenAI Chat / Embedding 리포트 생성
Langfuse 프롬프트 리포트 생성

관련 문서