Mintlify로 개발자 문서 사이트 만들기: docs.json, MDX 컴포넌트, OpenAPI 레퍼런스 자동 생성

작성 0xmote · 2026년 8월 12일 · 12분 읽기 · 수정 2026년 10월 13일 중급 tutorial

이 글의 핵심

자동 생성된 API 페이지가 빈약해 보인다면 대개 도구보다 OpenAPI 스펙의 설명과 예시가 부족한 탓입니다. 스펙을 단일 진실 공급원에 가깝게 유지하는 방법, MDX 가이드와 자동 API 페이지의 역할 분담, 저장소·브랜치 전략과 로컬 검증, 출시 후 운영까지 문서 사이트를 꾸준히 관리하는 흐름을 정리합니다.

들어가며

Mintlify는 Git 저장소의 MDX 파일과 OpenAPI 스펙을 묶어 “제품 문서 + API 레퍼런스” 사이트로 배포해 주는 플랫폼입니다. 이 글에서는 설정 파일(docs.json, 과거 mint.json), MDX 작성, OpenAPI·AsyncAPI 기반 API 페이지 생성, 내비게이션과 테마 설정, 팀에서 API 문서를 운영하는 순서를 다룹니다. Markdown, Git, REST API, JSON에 익숙한 독자를 기준으로 합니다.

Mintlify란 무엇인가

Mintlify는 개발자 대상 제품 문서(Developer Documentation) 사이트를 만들기 위한 플랫폼입니다. 정적 페이지 생성·호스팅·검색·API 플레이그라운드 등을 문서 작성 워크플로와 통합하여, Notion이나 순수 정적 사이트 제너레이터만으로는 부담스러운 버전 관리된 기술 문서 + API 레퍼런스를 한곳에서 운영할 수 있게 합니다.

왜 별도 “문서 플랫폼”이 필요한가

README와 별도 위키에 같은 정보가 흩어지면 어느 쪽이 최신인지 알기 어렵습니다. 문서를 Git으로 관리하면 코드와 같은 PR 리뷰를 거치고 릴리스 시점에 맞춰 배포할 수 있습니다. API 문서는 OpenAPI(Swagger) 스펙만 있으면 엔드포인트 목록, 요청/응답 스키마, 예제 코드를 일관된 UI로 보여 줄 수 있고, 문서가 커질수록 필요한 내비게이션과 전문 검색도 플랫폼이 기본으로 제공합니다.

핵심 구성 요소

구분	설명
콘텐츠	MDX(Markdown + JSX)로 페이지 작성
설정	문서 루트의 `docs.json`(구 `mint.json`)로 전역 동작 정의
API 레퍼런스	OpenAPI·AsyncAPI 스펙을 연결해 페이지·플레이그라운드 생성
CLI	`mint` CLI로 로컬 미리보기·설정 마이그레이션 등 수행
배포	Git 연동을 통한 빌드·호스팅(플랫폼 문서에 따름)

이 구조 덕분에 마케팅 사이트는 별도 CMS, 개발자 문서는 Mintlify처럼 역할을 나누기 쉽습니다.

mint.json과 docs.json: 설정의 중심

과거 Mintlify는 저장소 루트의 mint.json 을 중심 설정 파일로 사용했습니다. 현재는 docs.json 이 공식 설정 파일이며, 공식 문서에 따르면 mint.json은 더 이상 권장되지 않습니다.

필수 필드 네 가지

동작하는 최소 사이트를 만들려면 다음 네 가지를 docs.json에 정의합니다.

필드	역할
`name`	프로젝트·조직 이름
`theme`	레이아웃 테마(예: `mint`, `maple` 등)
`colors.primary`	브랜드 primary 색상(HEX)
`navigation`	사이드바 등 문서 정보 구조

에디터 자동완성을 위해 파일 상단에 $schema 를 두는 것이 권장됩니다.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme API Docs",
  "colors": {
    "primary": "#2563eb"
  },
  "navigation": {
    "groups": [
      {
        "group": "시작하기",
        "pages": ["index", "quickstart"]
      },
      {
        "group": "가이드",
        "pages": ["guides/authentication", "guides/rate-limits"]
      }
    ]
  }
}

위 예시에서 pages 배열의 문자열은 콘텐츠 파일 경로(확장자 제외)와 대응합니다. 폴더 구조를 바꾸면 navigation도 함께 맞춰야 사이드바와 실제 파일이 어긋나지 않습니다.

mint.json에서 업그레이드하는 방법

기존 저장소에 mint.json만 있다면 Mintlify CLI를 최신 버전으로 설치한 뒤 문서 루트에서 mint upgrade를 실행해 docs.json을 생성합니다(CLI 버전에 따라 명령이 다를 수 있으니 공식 업그레이드 안내를 확인하세요). 생성된 docs.json에서 내비게이션, 색, API 경로가 제대로 옮겨졌는지 검토하고 mint dev로 미리 본 다음, 문제가 없으면 mint.json을 삭제합니다.

이 과정은 “설정 파일 이름과 스키마의 표준화”이지, 문서 본문(MDX) 작성 방식이 완전히 바뀐다는 뜻은 아닙니다. 다만 팀 내 문서·CI 스크립트에서 mint.json을 참조하고 있다면 경로를 모두 docs.json으로 바꿔야 합니다.

설정 분할: `$ref`

문서가 많아지면 docs.json이 비대해집니다. Mintlify는 JSON 내부에 $ref 로 다른 JSON 파일을 끌어와 병합할 수 있습니다. 예를 들어 navigation만 config/navigation.json으로 분리하면 역할별로 리뷰하기 쉽습니다. 경로는 프로젝트 루트 기준 상대 경로이며, 문서에 명시된 대로 경로 트래버설은 허용되지 않습니다.

MDX와 컴포넌트

Mintlify 페이지는 MDX로 작성하는 것이 일반적입니다. Markdown의 가독성에 React 계열 컴포넌트를 섞어 알림(Callout), 단계, 카드, 코드 탭 등을 표현할 수 있습니다.

작성 시 유의할 점

경고·팁·절차 같은 반복 패턴을 컴포넌트로 통일하면 페이지마다 모양과 톤이 맞습니다. Mintlify의 기본 제공 컴포넌트(<Note>, <Warning>, <Steps>, <Card>, <CodeGroup> 등)는 전역으로 등록되어 있어 페이지에서 따로 import하지 않아도 됩니다. 반대로 직접 만든 스니펫이나 React 컴포넌트는 import해야 하므로, 둘을 섞어 쓸 때 혼동하기 쉽습니다. 컴포넌트 목록은 릴리스마다 바뀔 수 있으니 공식 Components 문서를 기준으로 삼습니다.

페이지 제목은 MDX frontmatter의 title이 h1으로 렌더링되므로, 본문은 ##부터 시작하는 것이 헤딩 구조와 SEO 모두에 좋습니다. 코드 블록에는 언어 태그를 붙여야 하이라이트가 적용되고, API 예제는 OpenAPI의 x-codeSamples와 MDX 본문 코드가 서로 다른 내용을 보여 주지 않도록 한쪽을 기준으로 관리합니다.

API Reference 자동 생성 (OpenAPI·AsyncAPI)

API 문서의 심장은 스펙과 문서 UI의 동기화입니다. Mintlify는 docs.json의 api 객체로 OpenAPI·AsyncAPI를 연결하며, 플레이그라운드·예제 코드 생성·파라미터 표시 방식을 조정합니다.

OpenAPI 연결

api.openapi에는 단일 파일 경로나 원격 URL을 문자열로 줄 수 있고, v1, v2처럼 스펙이 여러 개라면 배열로 나열합니다. 스펙 파일과 생성될 페이지 위치를 함께 지정하려면 source와 directory를 가진 객체 형태를 씁니다.

예시:

{
  "api": {
    "openapi": [
      "openapi/v1.yaml",
      "https://api.example.com/openapi.json"
    ],
    "playground": {
      "display": "interactive"
    },
    "params": {
      "expanded": "all"
    },
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    }
  }
}

playground.display 는 interactive(기본)·simple·none·auth 등으로, 팀 정책·보안 요구에 맞게 조절합니다. 공개 API라면 interactive가 사용자 경험에 유리하며, 내부 전용이면 인증 연동 옵션을 검토합니다.

AsyncAPI

이벤트·메시지 기반 API(WebSocket, Kafka 등)는 AsyncAPI로 기술할 수 있으며, api.asyncapi에 경로·URL·디렉터리를 연결하는 방식이 OpenAPI와 유사합니다. 실시간 채널이 많은 제품은 REST 문서와 AsyncAPI 문서를 내비게이션에서 인접 그룹으로 두면 독자가 맥락을 잃지 않습니다.

스펙 품질이 곧 문서 품질

자동 생성 페이지의 품질은 스펙의 완전성에 달려 있습니다. 요약(summary)과 태그는 페이지 제목과 사이드바 그룹이 되므로 비어 있으면 경로 문자열이 그대로 노출됩니다. examples와 스키마 설명이 빠진 엔드포인트는 플레이그라운드에서도 빈 폼만 보이고, 보안 스키마(Bearer, OAuth2 등)를 정의하지 않으면 독자가 인증 방법을 추측해야 합니다.

CI에서 Spectral 등으로 OpenAPI 린트를 돌리고, 릴리스마다 스펙을 아티팩트로 남기면 Mintlify 쪽 설정과 같은 커밋을 가리키게 하기 쉽습니다.

검색과 내비게이션

내비게이션(`navigation`)

navigation.groups는 문서의 목차입니다. 그룹 이름은 제품 도메인(시작하기, API, SDK, 운영)에 맞추고, pages 순서는 온보딩 흐름을 반영하는 것이 좋습니다. 페이지가 많아지면 그룹 안에 하위 그룹을 중첩하거나 tabs로 최상위 영역을 나누고, $ref로 내비게이션만 별도 파일로 분리하면 정보 구조를 바꾸는 PR을 따로 리뷰할 수 있습니다.

검색

Mintlify는 사이트 내 검색을 기본 제공하며, docs.json의 seo·search 설정으로 메타 태그와 검색창 동작을 조정할 수 있습니다(세부 키는 스키마 레퍼런스 참고). 검색은 결국 페이지 텍스트에 기대므로, 사용자가 실제로 입력할 용어(에러 코드, 쿼리 파라미터 이름)를 페이지 제목이나 첫 단락에 넣는 것이 효과적입니다. 같은 개념을 여러 이름으로 부른다면(예: “JWT”와 “Bearer 토큰”) 한 페이지에서 동의어를 짧게 연결해 두면 어느 쪽으로 검색해도 찾을 수 있습니다.

Navbar·Footer·리다이렉트

글로벌 설정에서는 네비게이션 바, 푸터, 배너, 리다이렉트 등 사이트 전체 UX 요소를 다룹니다. API 레퍼런스만이 아니라 가격 페이지·상태 페이지·지원 포털로의 외부 링크를 여기서 정리하면 “문서만 보는 사용자”와 “제품 전체를 보는 사용자” 모두에게 일관된 내비를 제공할 수 있습니다.

커스터마이징과 테마

테마(`theme`)

theme 값은 Mintlify가 제공하는 레이아웃 프리셋을 선택합니다. 테마마다 사이드바와 본문 폭, 헤더 배치가 다르므로, API 레퍼런스처럼 정보 밀도가 높은 페이지가 많다면 mint dev로 실제 페이지를 띄워 긴 스크롤과 사이드바 동작을 확인한 뒤 고르는 것이 좋습니다.

브랜딩

colors.primary 외에도 로고·파비콘·폰트·배경 등 Appearance 관련 필드로 브랜드를 맞춥니다. 디자인 시스템의 primary 색을 그대로 쓰되, 다크 모드·대비 접근성을 디자인 팀과 한 번 검토하는 것이 안전합니다.

통합(Integrations)

분석·채팅·기타 서드파티는 docs.json의 Integrations 섹션에서 설정합니다. 어떤 이벤트를 수집할지 개인정보 처리방침과 맞추고, 개발자 문서 특성상 “코드 복사”, “API 호출 시도” 같은 행동 지표가 유용할 수 있습니다.

실전: API 문서 구축 워크플로

저장소와 브랜치 전략

문서는 전용 저장소나 모노레포의 docs/ 디렉터리에 둡니다. Mintlify는 연결된 브랜치에 푸시될 때마다 배포하므로, 그 브랜치(보통 main)에는 항상 배포 가능한 상태만 두고 문서 변경은 PR로 모읍니다. API 스펙이 백엔드 저장소에서 만들어진다면 CI에서 문서 저장소로 복사하는 단계를 두어 사람이 손으로 옮기지 않게 합니다.

OpenAPI를 “단일 진실 공급원”에 가깝게

스펙은 손으로 고치는 문서가 아니라 백엔드 빌드 산출물로 생성해 커밋하거나, 안정된 URL을 docs.json에 직접 지정하는 편이 코드와 어긋나지 않습니다. 브레이킹 체인지는 스펙 diff와 문서 changelog를 함께 확인합니다.

MDX 가이드와 자동 API 페이지의 역할 분담

엔드포인트별 요청/응답 필드는 OpenAPI 자동 페이지에 맡기고, MDX 가이드에서는 개념, 사용 시나리오, 트러블슈팅, 그리고 “왜 이렇게 설계했는지”를 씁니다. 같은 필드 설명을 양쪽에 쓰면 한쪽만 갱신되는 일이 반드시 생깁니다.

로컬 검증

CLI로 로컬 서버를 띄워 내비·검색·플레이그라운드를 PR 전에 확인합니다. 특히 CORS·프록시 설정은 실제 API와 연결할 때 이슈가 되기 쉬우므로 스테이징 환경에서 한 번 검증합니다.

출시 후 운영

폐기 예정인 엔드포인트는 스펙에 deprecated: true를 명시하면 자동 페이지에 표시되고, MDX 마이그레이션 가이드로 링크를 겁니다. API 버전을 나눌 때는 스펙 파일을 v1/v2로 분리하고 내비게이션도 버전별 그룹(또는 versions 설정)으로 나눕니다.

Mintlify로 개발자 문서 사이트 만들기: docs.json, MDX 컴포넌트, OpenAPI 레퍼런스 자동 생성

이 글의 핵심

들어가며

Mintlify란 무엇인가

왜 별도 “문서 플랫폼”이 필요한가

핵심 구성 요소

mint.json과 docs.json: 설정의 중심

필수 필드 네 가지

mint.json에서 업그레이드하는 방법

설정 분할: `$ref`

MDX와 컴포넌트

작성 시 유의할 점

API Reference 자동 생성 (OpenAPI·AsyncAPI)

OpenAPI 연결

AsyncAPI

스펙 품질이 곧 문서 품질

검색과 내비게이션

내비게이션(`navigation`)

검색

Navbar·Footer·리다이렉트

커스터마이징과 테마

테마(`theme`)

브랜딩

통합(Integrations)

실전: API 문서 구축 워크플로

저장소와 브랜치 전략

OpenAPI를 “단일 진실 공급원”에 가깝게

MDX 가이드와 자동 API 페이지의 역할 분담

로컬 검증

출시 후 운영

참고 링크

같이 보면 좋은 글

이 글의 핵심

들어가며

Mintlify란 무엇인가

왜 별도 “문서 플랫폼”이 필요한가

핵심 구성 요소

mint.json과 docs.json: 설정의 중심

필수 필드 네 가지

mint.json에서 업그레이드하는 방법

설정 분할: $ref

MDX와 컴포넌트

작성 시 유의할 점

API Reference 자동 생성 (OpenAPI·AsyncAPI)

OpenAPI 연결

AsyncAPI

스펙 품질이 곧 문서 품질

검색과 내비게이션

내비게이션(navigation)

검색

Navbar·Footer·리다이렉트

커스터마이징과 테마

테마(theme)

브랜딩

통합(Integrations)

실전: API 문서 구축 워크플로

저장소와 브랜치 전략

OpenAPI를 “단일 진실 공급원”에 가깝게

MDX 가이드와 자동 API 페이지의 역할 분담

로컬 검증

출시 후 운영

참고 링크

같이 보면 좋은 글

설정 분할: `$ref`

내비게이션(`navigation`)

테마(`theme`)