mint.json과 docs.json 중 무엇을 써야 하나요?

신규 프로젝트는 docs.json을 사용합니다. mint.json은 더 이상 권장되지 않으며, Mintlify CLI(mint dev 등)로 docs.json으로 마이그레이션한 뒤 mint.json을 삭제하면 됩니다.

OpenAPI만 있으면 API 문서 페이지가 자동 생성되나요?

docs.json의 api.openapi에 스펙 경로나 URL을 지정하면 API 레퍼런스 페이지와 플레이그라운드가 생성됩니다. 디렉터리·다중 스펙·MDX와의 혼합도 설정으로 제어할 수 있습니다.

Mintlify 완벽 가이드 — 개발자 문서 플랫폼

2026년 4월 17일 · 45분 읽기 · 수정 2026년 4월 17일 중급 tutorial

이 글의 핵심

Mintlify는 MDX 기반 개발자 문서 호스팅 플랫폼입니다. docs.json(구 mint.json)로 내비·브랜딩·OpenAPI 연동을 통합하고, 검색·API 플레이그라운드·테마로 프로덕션급 문서 사이트를 만드는 방법을 단계별로 다룹니다.

이 글을 읽으면 (약 45분)

TL;DR: Mintlify는 Git 연동·MDX·OpenAPI를 한 스택으로 묶어 “제품 문서 + API 레퍼런스”를 빠르게 출시할 수 있는 플랫폼입니다. 이 글에서는 설정 파일(docs.json, 과거 mint.json), MDX 컴포넌트, API 자동 생성, 검색·내비게이션, 테마·브랜딩, 실무에서의 API 문서 구축 순서까지 정리합니다.

다루는 내용

Mintlify의 역할과 Git·호스팅·CLI 생태계
docs.json 스키마와 mint.json에서의 이전(마이그레이션)
MDX 작성 패턴과 Mintlify 컴포넌트 활용
OpenAPI·AsyncAPI 기반 API 레퍼런스·플레이그라운드
검색·사이드바·내비게이션 설계
테마·색·로고 등 커스터마이징
API 문서를 실제로 올릴 때의 권장 워크플로

난이도: 중급 (Markdown·Git·REST API·JSON에 익숙한 독자 기준)

1. Mintlify란 무엇인가

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

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

동일한 정보의 이중 관리 방지: README와 별도 위키에 흩어지면 최신화가 어렵습니다. Git 기반 문서는 PR 리뷰와 릴리스에 맞출 수 있습니다.
API 문서의 구조화: OpenAPI(Swagger) 스펙만 있어도 엔드포인트 목록·요청/응답 스키마·예제 코드를 일관된 UI로 노출할 수 있습니다.
검색과 정보 구조: 성장하는 문서는 내비게이션(그룹·계층) 과 전문 검색이 없으면 탐색 비용이 커집니다. Mintlify는 이를 제품 기능으로 포함합니다.

1.2 핵심 구성 요소

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

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

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

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

2.1 필수 필드 네 가지

동작하는 최소 사이트를 만들려면 다음 네 가지를 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도 함께 맞춰야 사이드바와 실제 파일이 어긋나지 않습니다.

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

기존 저장소에 mint.json만 있는 경우:

Mintlify CLI 설치 후 mint dev 등으로 docs.json 생성·변환
생성된 docs.json을 검토(내비·색·API 경로 등)
문제 없으면 mint.json 삭제

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

2.3 설정 분할: `$ref`

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

3. MDX와 컴포넌트

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

3.1 MDX가 문서에 적합한 이유

재사용: 동일한 패턴(경고·팁·절차)을 컴포넌트로 통일하면 디자인과 톤이 맞습니다.
인터랙션: API 플레이그라운드·일부 임베드 UI와 같은 기능과 같은 저장소에서 다루기 쉽습니다.
타입·린트: 팀 정책에 따라 MDX용 ESLint·포맷터를 붙여 품질을 관리할 수 있습니다.

3.2 작성 시 유의할 점

컴포넌트 이름과 import: Mintlify가 제공하는 컴포넌트 세트는 공식 문서의 “Components” 범주를 따릅니다. 버전 업 시 deprecated 안내를 확인하세요.
SEO와 헤딩 구조: 하나의 페이지에 h1이 과도하게 많아지지 않도록, 문서 템플릿에서 제목 계층(##, ###) 규칙을 팀 합의로 정하는 것이 좋습니다.
코드 블록: 언어 태그를 명시하면 하이라이트와 복사 UX가 좋아집니다. API 예제는 OpenAPI의 x-codeSamples나 MDX 내 코드와 출처가 일치하도록 관리하세요.

구체적인 컴포넌트 이름은 릴리스마다 추가될 수 있으므로, 프로젝트를 시작할 때 공식 컴포넌트 갤러리·문서의 최신 페이지를 북마크해 두는 것을 권장합니다.

4. API Reference 자동 생성 (OpenAPI·AsyncAPI)

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

4.1 OpenAPI 연결

api.openapi에는 다음과 같은 형태를 사용할 수 있습니다.

단일 파일·URL: "openapi.json" 또는 원격 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가 사용자 경험에 유리하고, 내부 전용이면 인증 연동 옵션을 검토합니다.

4.2 AsyncAPI

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

4.3 스펙 품질이 곧 문서 품질

자동 생성은 스펙의 완전성에 의존합니다. 다음을 점검하세요.

요약·태그·operationId: 사이드바 정렬·검색 키워드에 영향을 줍니다.
예제·스키마: examples가 빈 엔드포인트는 플레이그라운드에서도 허전해 보입니다.
인증: 보안 스키마(Bearer, OAuth2 등) 정의가 없으면 독자가 호출 방법을 추측해야 합니다.

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

5. 검색과 내비게이션

5.1 내비게이션(`navigation`)

navigation.groups는 문서의 목차입니다. 그룹 이름은 제품 도메인(시작하기, API, SDK, 운영)에 맞추고, pages 순서는 온보딩 흐름을 반영하는 것이 좋습니다. 페이지가 늘면:

상위 그룹만 사이드바에 두고 하위는 폴더 경로로 정리
$ref로 내비만 별도 파일로 분리해 정보 구조 변경 PR을 독립적으로 리뷰

5.2 검색

Mintlify는 사이트 내 검색을 지원하며, docs.json의 SEO·search 관련 설정으로 메타·동작을 조정할 수 있습니다(세부 키는 스키마 레퍼런스 참고). 실무 팁은 다음과 같습니다.

페이지 제목·첫 단락에 사용자가 검색할 용어(에러 코드, 쿼리 파라미터 이름)를 넣습니다.
동일한 개념에 여러 표기(예: “JWT”와 “Bearer 토큰”)가 있으면 한 페이지에서 동의어를 짧게 연결해 줍니다.

5.3 Navbar·Footer·리다이렉트

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

6. 커스터마이징과 테마

6.1 테마(`theme`)

theme 값은 Mintlify가 제공하는 레이아웃 프리셋을 선택합니다. 문서 성격에 맞게 고릅니다.

짧은 튜토리얼 중심: 시각적으로 가벼운 테마가 어울릴 수 있습니다.
대규모 API 레퍼런스: 한 화면에 정보 밀도가 높아지므로, 긴 스크롤·사이드바 동작을 로컬에서 미리 확인합니다.

6.2 브랜딩

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

6.3 통합(Integrations)

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

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

아래 순서는 팀에 도입할 때 재현하기 쉬운 권장 순서입니다.

7.1 저장소와 브랜치 전략

문서 전용 저장소 또는 모노레포의 docs/ 패키지로 둡니다.
main 에는 항상 배포 가능한 상태만 두고, 문서 변경은 PR로 모읍니다.
API 스펙은 백엔드 저장소에서 생성해 문서 저장소로 복사하거나 CI에서 동기화합니다.

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

가능하면 빌드 산출물로 openapi.yaml을 생성해 문서 저장소에 커밋하거나, 안정된 URL을 docs.json에 직접 지정합니다.
브레이킹 체인지는 스펙 diff와 문서 changelog를 함께 봅니다.

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

개념·시나리오·트러블슈팅: MDX 가이드에 길게 씁니다.
엔드포인트별 요청/응답 필드: OpenAPI 자동 페이지에 맡깁니다.
중복 서술을 피하고, 가이드에서는 “왜 이렇게 설계했는지”에 집중합니다.

7.4 로컬 검증

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

7.5 출시 후 운영

Deprecated API: 스펙에 deprecated를 명시하고, MDX에 마이그레이션 가이드를 링크합니다.
버전 정책: URL 경로나 스펙 파일을 v1/v2로 나누고, 내비게이션 그룹도 버전별로 분리합니다.

8. 정리

Mintlify는 Git·MDX·OpenAPI를 묶어 개발자 문서를 “제품”처럼 운영할 수 있게 합니다. 설정은 docs.json 이 중심이며, 과거 mint.json 은 CLI로 이전한 뒤 폐기하는 흐름이 공식 가이드와 일치합니다. API 레퍼런스는 스펙 품질이 곧 완성도이므로, 린트·CI·버전 정책을 문서 레포와 함께 설계하는 것이 장기적으로 가장 큰 이득입니다.

공식 문서의 Global settings, API settings, Schema reference를 함께 열어 두면 docs.json 확장 시 안전하게 필드를 추가할 수 있습니다.