버전 관리
API는 /v1 prefix 아래에서 버전이 관리됩니다 — 현재 상태는 다음과 같습니다.
모든 endpoint는 /v1 아래에 있습니다
이 레퍼런스의 모든 path는 /v1 prefix가 붙습니다(/chat이 아니라 /v1/chat). 유일한 예외는 /health이며, 이는
의도적으로 prefix가 없습니다 — 이는 버전이 관리되는 공개 계약(contract)의 일부가 아니라 인프라 liveness
check이며, 모니터링 도구는 prefix 없는 path를 가리킵니다.
이제 API 자체가 머신이 읽을 수 있는 OpenAPI spec을 공개합니다 — 원본 JSON은 /docs-json에, 인터랙티브한 Swagger
UI는 /docs에 있습니다 — 이는 실제 route handler와 request/response 타입으로부터 직접 생성되므로, 손으로 쓴
글처럼 조용히 어긋날(drift) 수 없습니다. 이 페이지는 아직은 손으로 작성되어 있습니다. 손으로 설명하는 대신 생성된
spec을 직접 렌더링하도록 옮겨가는 것이 자연스러운 다음 단계이지만, 아직 이루어지지 않았습니다.