Mintlify는 OpenAPI 3.0 및 3.1 사양(JSON 또는 YAML 형식)을 브라우저에서 직접 테스트할 수 있는 대화형 API 레퍼런스 문서로 자동 변환하는 플랫폼입니다. 엔지니어와 테크니컬 라이터가 요청 파라미터, 헤더, 응답 본문 스키마를 수동으로 정리할 필요 없이, Mintlify가 규격을 분석하여 다국어 코드 샘플과 실제 요청을 보낼 수 있는 실시간 테스트 콘솔(Playground)을 구성합니다.
이 플랫폼은 Docs-as-code(코드형 문서) 방식을 따릅니다. OpenAPI 사양 파일은 Markdown 문서와 함께 Git 저장소에서 관리되며, 중앙 설정 파일(docs.json, 구버전의 경우 mint.json)을 통해 전체 구조를 제어합니다. 팀의 운영 방식에 따라 사양 파일에서 전체 API 레퍼런스를 자동으로 구성하는 무관리 방식과, 개별 MDX 문서에 특정 엔드포인트를 연결하여 비즈니스 가이드나 주의사항을 덧붙이는 하이브리드 방식 중 적합한 모델을 선택할 수 있습니다.
사전 요구 사항 및 규격 사양
Mintlify와 통합하기 전, 준비한 사양 파일이 아래 요구 사항을 충족하는지 확인해야 합니다:
- 지원 버전: Mintlify는 OpenAPI Specification(OAS) 3.0 및 3.1을 기본 지원합니다. 레거시 Swagger 2.0 형식을 사용 중이라면 사양을 OpenAPI 3.0으로 먼저 변환해야 합니다.
- 파일 형식: 표준 JSON(
.json) 및 YAML(.yaml또는.yml) 파일을 모두 지원합니다. - 참조($ref) 제약: 단일 문서 내부에서의 스키마 참조(예:
$ref: '#/components/schemas/User')는 지원되지만, 여러 파일로 분할된 외부 참조는 지원되지 않습니다. 사양이 여러 파일에 나뉘어 있다면 Mintlify에 연결하기 전 번들링 도구(Redocly CLI 또는@apidevtools/swagger-cli등)를 사용해 하나의 파일로 병합해야 합니다.
1단계: OpenAPI 사양 파일 배치
사양 파일은 로컬 Git 저장소에 보관하거나 원격 URL로 직접 연결할 수 있습니다:
-
로컬 저장소 배치(권장): 문서 저장소 내에 사양 파일을 커밋합니다. 일반적으로 프로젝트 루트 디렉터리(예:
openapi.json,openapi.yaml) 또는 전용 디렉터리(예:api-reference/openapi.json,specs/v1.yaml)에 배치합니다. -
호스팅된 원격 URL 연결: 백엔드 CI/CD 파이프라인에서 최신 OpenAPI 사양을 오브젝트 스토리지나 CDN에 자동으로 배포하는 구조라면 HTTPS URL을 직접 지정할 수 있습니다(예:
https://api.example.com/specs/openapi.json). 프로덕션 배포 시에는 반드시 HTTPS 프로토콜을 사용해야 합니다.
2단계: docs.json에서 네비게이션 설정
문서 좌측 사이드바에 API 레퍼런스를 표시하려면 docs.json의 navigation 블록에 사양 파일을 지정합니다.
방식 A: 레퍼런스 전체 자동 생성
사양 파일의 모든 엔드포인트를 자동으로 읽어 들이고, OpenAPI의 tags 값을 기준으로 그룹화하여 페이지를 생성하려는 경우 탭이나 그룹 내에 사양 경로를 직접 선언합니다:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme API Docs",
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{
"group": "시작하기",
"pages": ["introduction", "quickstart"]
}
]
},
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
}
이 설정을 적용하면 Mintlify는 paths에 정의된 모든 경로를 분석하여 HTTP 메서드, 요약 설명, 파라미터 표, 응답 스키마를 추출하고, 별도의 MDX 파일을 작성하지 않아도 완전한 탐색 구조를 생성합니다.
다중 사양 파일 관리
서비스가 여러 마이크로서비스로 나뉘어 있거나 API 버전이 분리되어 있다면 파일 경로 배열을 전달합니다:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"specs/v1/auth.json",
"specs/v1/billing.json",
"specs/v2/core.json"
]
}
]
}
}
3단계: MDX 페이지를 통한 정밀한 문서 구성
완전 자동화는 관리 부담이 적지만, 테크니컬 라이터는 특정 핵심 엔드포인트에 비즈니스 규칙, 사전 요구 권한, 호출 제한 경고, 아키텍처 다이어그램 등을 함께 작성해야 하는 경우가 많습니다. Mintlify는 MDX의 Frontmatter 속성을 통해 특정 엔드포인트를 페이지에 직접 바인딩할 수 있습니다.
1. MDX 파일과 특정 엔드포인트 연결
MDX 파일(예: api-reference/users/create.mdx)을 생성하고 상단 Frontmatter의 openapi 필드에 대상 HTTP 메서드와 경로를 명시합니다:
---
title: "사용자 생성"
sidebarTitle: "사용자 생성"
description: "조직 내에 새로운 사용자 계정을 등록합니다"
openapi: "POST /v1/users"
---
## 사전 요구 사항
이 엔드포인트를 호출하기 전, 클라이언트 애플리케이션에 `users:write` 권한 스코프가 부여되어 있는지 확인하십시오.
<Warning>
사용자 이메일 주소는 조직 내에서 고유해야 합니다. 이미 존재하는 이메일로 요청할 경우 `409 Conflict` 오류가 반환됩니다.
</Warning>
## Webhook 알림
사용자 등록이 완료되면 시스템은 설정된 Webhook 엔드포인트로 `user.created` 이벤트를 자동 발송합니다.
Mintlify는 사양 파일에서 POST /v1/users 정의를 찾아 대화형 요청 빌더와 파라미터 명세를 현재 페이지에 자동으로 삽입하며, 사용자가 작성한 설명문과 매끄럽게 결합합니다.
여러 사양 파일을 사용하는 프로젝트의 경우 충돌을 방지하기 위해 파일 경로를 접두어로 명시합니다:
---
title: "사용자 생성"
openapi: "specs/v1/auth.json POST /v1/users"
---
2. Mintlify 스크래퍼를 통한 MDX 일괄 생성
수십 개의 엔드포인트에 대해 개별 MDX 뼈대 파일을 생성한 후 편집하고자 할 때는 공식 스크래핑 유틸리티를 실행합니다:
npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference
이 명령은 사양을 분석하여 api-reference 폴더 내에 적절한 Frontmatter가 구성된 개별 MDX 파일들을 자동으로 생성해 줍니다.
4단계: 대화형 API 테스트 콘솔(Playground) 구성
Mintlify의 대화형 콘솔은 독자가 문서 내에서 파라미터를 입력하고 실제 API 요청을 보낼 수 있게 지원합니다. 원활한 동작을 위해 다음 사항들을 확인해야 합니다:
1. 기본 서버 주소(Base URL) 정의
Mintlify는 OpenAPI 사양 파일의 servers 배열을 읽어 테스트 요청을 전송할 대상 주소를 파악합니다:
servers:
- url: https://api.example.com/v1
description: 프로덕션 서버
- url: https://staging.api.example.com/v1
description: 스테이징 샌드박스
여러 서버가 선언되어 있으면 콘솔에 환경을 선택할 수 있는 드롭다운 메뉴가 노출됩니다.
2. 인증 체계 및 기본 테스트 키 설정
components.securitySchemes에 인증 방식을 선언하면 콘솔에 Bearer Token, API Key 등의 입력 필드가 표시됩니다:
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: API 액세스 토큰을 입력하십시오
security:
- bearerAuth: []
샌드박스 환경에서 독자가 즉시 테스트해 볼 수 있도록 기본 테스트용 키를 제공하려면 x-default 확장 필드를 사용할 수 있습니다:
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "demo_pk_live_testing123"
}
}
}
}
3. CORS(교차 출처 리소스 공유) 처리
테스트 콘솔의 HTTP 요청은 브라우저에서 직접 발송되므로, 백엔드 서버에서 CORS 요청을 허용해야 통신 오류가 발생하지 않습니다:
Access-Control-Allow-Origin: *(또는 문서 도메인)Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, X-API-Key
서버가 브라우저의 사전 검사(OPTIONS) 요청을 차단할 경우 터미널의 curl로는 성공하더라도 문서상의 콘솔에서는 실패합니다.
5단계: OpenAPI Overlays를 통한 비침습적 사양 수정
엔지니어링 팀이 자동 생성한 사양에는 내부용 엔드포인트가 포함되어 있거나 일반 개발자가 이해하기 어려운 설명이 기재되어 있을 수 있습니다. 사양 원본을 직접 수정하지 않고도 문서 빌드 시점에 내용을 보정할 수 있도록 Mintlify는 **OpenAPI Overlay Specification(v1.1.0)**을 지원합니다.
오버레이 파일(예: overlays/public-filter.yaml)을 만들고 JSONPath 구문으로 update, remove, copy 규칙을 정의합니다:
overlay: 1.1.0
info:
title: 공개 문서용 사양 보정
version: 1.0.0
extends: ./openapi.json
actions:
- target: $.info.description
update: "Acme 공식 개발자 문서에 오신 것을 환영합니다. 엔드포인트를 탐색하고 직접 테스트해 보십시오."
- target: $.paths['/internal/system-health']
remove: true
- target: $.paths['/v1/billing'].post.summary
update: "정기 결제 구독 생성"
작성한 오버레이를 docs.json에 연결합니다:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": {
"source": "openapi.json",
"overlays": ["overlays/public-filter.yaml"]
}
}
]
}
}
Mintlify는 문서를 컴파일할 때 오버레이를 자동으로 적용하여 내부 엔드포인트를 숨기고 설명을 가다듬습니다. 원본 사양 파일을 수정할 필요가 없어 백엔드 파이프라인과의 충돌을 방지합니다.
6단계: 로컬 테스트 및 CI/CD 자동 검증
문서를 프로덕션에 배포하기 전, Mintlify CLI를 통해 로컬에서 정합성을 확인합니다:
-
개발 서버 실행:
npm i -g mintlify mint dev -
로컬 실행 중인 사양 서비스 테스트: 로컬 개발 서버에서 동적으로 사양을 제공하는 경우(예:
http://localhost:8000/openapi.json), 로컬 스키마 접근 플래그를 붙여 실행합니다:mint dev --local-schema -
엄격한 유효성 검증: 참조 오류 및 스키마 결함을 사전에 탐지합니다:
mint validate -
CI/CD 파이프라인 연동: GitHub Actions 또는 GitLab CI에
mint validate를 추가하십시오. 개발자가 새로운 API 사양을 커밋할 때마다 사양의 유효성을 자동으로 검증하여 오류가 있는 문서가 배포되는 것을 사전에 차단할 수 있습니다.