API 문서의 AI/자동화 도구 친화적 구조화 산출물 제공

[bottlenote-app]

배경

현재 Product API/Admin API 문서는 GitHub Pages HTML 형태로 제공되고 있다.

• Product API: https://bottle-note.github.io/bottle-note-api-server/bottle-note/product-api/product-api.html
• Admin API: https://bottle-note.github.io/bottle-note-api-server/bottle-note/admin-api/admin-api.html

HTML 문서는 사람이 확인하기에는 충분하지만, AI 에이전트나 자동화 도구가 API 스펙을 안정적으로 읽고 활용하기에는 구조화 정보가 부족한 것으로 파악된다.

문제

현재 문서 기준으로는 다음 작업이 어렵다.

• endpoint/path/method/request/response/error spec의 기계적 파싱
• Product API/Admin API 구분 자동 인식
• 최신 배포 문서 기준 API 변경사항 추적
• FE/PM/QA 에이전트가 API 계약을 근거로 이슈/PR/검증 작업 수행
• Swagger/OpenAPI처럼 JSON 기반으로 endpoint 목록과 schema 재사용

요청사항

AI 및 자동화 도구가 읽기 쉬운 API 문서 산출물을 추가 제공할 수 있는지 BE 관점에서 확인하고, 가능하다면 제공 방식을 설계한다.

우선순위 제안:

1. OpenAPI JSON/YAML 산출물 제공
2. Product API/Admin API를 구분한 JSON 문서 제공
3. endpoint별 method/path/description/request/response/error/example metadata 포함
4. GitHub Pages 배포 시 HTML 문서와 함께 최신 JSON 산출물도 배포
5. 기존 HTML 문서는 유지

확인 필요

• 현재 RestDocs/문서 생성 파이프라인에서 OpenAPI JSON/YAML 또는 endpoint metadata JSON을 HTML 문서와 함께 생성·배포할 수 있는지 확인이 필요하다.
• 어렵다면 기존 RestDocs 산출물을 기반으로 자동화 도구가 안정적으로 읽을 수 있는 최소 JSON 산출물 제공 가능성을 검토한다.

기대효과

• FE/API 연동 시 현재 배포된 API 계약을 자동 확인 가능
• PM/QA 이슈 정리 및 검증 기준 명확화
• AI 에이전트가 BE 레포 코드 추정이 아니라 배포 완료된 문서를 기준으로 API 분석 가능
• API 변경 영향도 파악 및 문서-구현 불일치 검출 기반 마련

참고

• 현재 기준으로 문서에 업데이트된 내용은 배포 완료된 API 계약 기준으로 본다.
• 관련 논의: Discord 메시지 https://discord.com/channels/1184472062119649430/1515025894958301294/1518080762698534942