Skip to main content

​
목표

GrowFit API Reference는 FastAPI의 **/openapi.json**을 읽어 자동 생성됩니다. 이 문서에서는
  • FastAPI → Mintlify 연결
  • 배포 환경/로컬 환경에서 OpenAPI 갱신
을 빠르게 설정하는 방법을 안내합니다.

​
1) Mintlify에 OpenAPI URL 연결

docs.json의 openapi 필드에 API 서버의 OpenAPI URL을 지정합니다. 
{
  "openapi": "<API_BASE_URL>/openapi.json"
}
예시: 
{
  "openapi": "https://api.growfit.ai/openapi.json"
}
TIP
  • 운영/스테이징 환경을 분리하고 싶다면, CI에서 docs.json을 환경별로 교체하거나 openapi 값을 주입하세요.

​
2) 배포 환경에서 스펙이 바로 반영되도록 하기

FastAPI는 기본적으로 /openapi.json을 제공합니다. 배포 환경에서도 해당 엔드포인트가 외부에서 접근 가능한지 확인하세요.
  • 인증이 필요한 경우: 읽기 전용 토큰을 만들어 openapi URL에 쿼리 파라미터로 전달
  • 접근 제한이 필요한 경우: 프록시/게이트웨이에서 /openapi.json만 허용

​
3) 로컬 개발/오프라인용 스펙 내보내기

실제 API 서버에 접근할 수 없는 상황이라면, 로컬에서 OpenAPI 스펙을 파일로 내보내 문서에 반영할 수 있습니다. 
python export_openapi.py
이 스크립트는 리포지토리 루트에 openapi.json을 생성합니다.
태그 기반 분류
  • 이 스크립트는 라우터 태그를 상위 그룹(예: Partner/User/Supervisor) 으로 정규화합니다.
  • 예: partner/session, partner/course → Partner로 묶여 API Reference에서 한 그룹으로 표시됩니다.
  • 추가로 그룹별 OpenAPI 파일(openapi-user.json, openapi-partner.json 등)을 만들어 문서 네비게이션에서 User/Partner/Supervisor/Utility Endpoints로 분리할 수 있습니다.

​
4) 문서 네비게이션에서 API Reference 분리

API Reference는 자동 생성 영역, Guide는 사람/AI가 작성하는 설명 영역으로 분리하는 것을 권장합니다.
  • Reference: 자동 생성 (OpenAPI)
  • Guides: 사용 시점, 에러 케이스, 권한/페이징 규칙 등 설명
자세한 작성 가이드는 아래 문서를 참고하세요.