OpenAPI 사양 다운로드

Minara 게이트웨이는 모든 엔드포인트에 대한 완전한 기계 판독 가능 설명을 OpenAPI 3.1 형식으로 제공합니다. 동일한 두 파일을 이 문서 사이트에서 정적 자산으로 제공합니다.

다운로드

• openapi.yaml: 사람이 읽기 쉬운 관용적 YAML입니다.
• openapi.json: 같은 사양을 JSON으로 인코딩한 파일입니다.

사양의 버전 필드는 Minara의 package.json 버전을 따르므로 체크인된 복사본을 릴리스 간에 비교할 수 있습니다.

포함 범위

apps/agent/src/gateway/api.ts에 등록된 모든 라우트에는 사양의 해당 항목이 있습니다. 스트리밍 채팅(/v1/chat/stream), 포트폴리오 및 무기한 선물 기능, 개인화 재구축기와 메모리 CRUD, 워크플로 관리, OAuth 흐름을 포함합니다. CLAUDE.md §8a는 실행 중인 게이트웨이와 이 파일의 차이를 P1 버그로 취급합니다. tests/unit/gateway/route-coverage.test.ts의 범위 테스트는 일치하는 RouteSpec 항목 없이 새 엔드포인트가 제공되는 것을 차단합니다.

사용 방법

Swagger UI: https://editor.swagger.io를 열고 File → Import URL을 선택한 뒤 배포된 /openapi.yaml URL을 붙여 넣습니다.

Postman: Import → Link를 선택하고 같은 URL을 붙여 넣습니다. Postman은 servers[].url을 인식해 호스트를 미리 채우며 Bearer 인증은 bearer 보안 체계로 설정합니다.

openapi-typescript: 완전한 타입의 클라이언트 코드를 생성합니다.

npx openapi-typescript https://your-host/openapi.yaml -o src/api-types.ts

curl 스모크 테스트: 게이트웨이에 인증이 켜져 있다면 Authorization: Bearer <GATEWAY_AUTH_TOKEN>를 사용합니다.

curl -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
     http://localhost:8080/v1/profile | jq

로컬 재생성

사양은 여기의 라우트별 참고 페이지를 구동하는 동일한 ROUTES 배열에서 빌드 시 생성됩니다. apps/agent/src/gateway/api.ts를 변경한 후 다음 명령으로 다시 빌드합니다.

npm --prefix docs run generate:openapi
# (or: npm --prefix docs run generate — runs both api + openapi)

생성기는 docs/public/openapi.{yaml,json}에 씁니다. 게이트웨이 변경과 함께 결과를 커밋하세요.