그러니까, 당신은 API에 대한 소문을 들었고—앱들이 서로 대화할 수 있게 해주는 마법 같은 다리들—이제는 전문적으로 문서화하고, 수고스럽지 않게 테스트하고 싶습니다. 여기서 Scalar가 등장합니다. API 문서화 및 테스트를 공원에서 산책하는 것처럼 쉽게 만들어주는 오픈 소스 보석입니다. 이 초보자 가이드에서는 멋진 API 문서를 만들고, 모든 것이 편안하고 즐거운 분위기 속에서 끝점을 테스트하는 방법을 알려드리겠습니다. 복잡한 코딩 기술은 필요 없습니다—단지 호기심과 노트북만 있으면 됩니다. 당신의 API 게임을 빛나게 할 준비가 되셨나요? 시작해봅시다!
Scalar란 무엇인가? 당신의 API 동반자
그렇다면 Scalar는 무엇일까요? API 문서화 및 테스트를 쉽게 할 수 있도록 설계된 현대적이고 오픈 소스 플랫폼입니다. 이것은 당신의 API 사양(예: OpenAPI/Swagger 파일)을 아름답고 인터랙티브한 문서로 변환해 주는 세련된 노트북과 같으며, 별도의 도구 없이 끝점을 테스트할 수 있는 놀이터를 제공합니다. Scalar는 REST API 클라이언트, 멋진 참조 자료 및 최고 수준의 OpenAPI 지원을 제공하며, “2011년에 설계된 것 같다”는 인상을 주지 않는 포장으로 제공됩니다. 매우 세련되고 개발자 친화적이며, 무료로 시작할 수 있습니다.
왜 Scalar를 사용해야 할까요? 지루한 텍스트 기반의 문서로부터 벗어나게 해주며, 브라우저에서 바로 API를 테스트할 수 있게 하고, 명확하고 클릭 가능한 참조 자료로 팀의 만족도를 높여 줍니다. 결제 API 문서화 중이라면, 혹은 할 일 앱을 테스트 중이라면, Scalar가 함께합니다. 설정해 보겠습니다!
Scalar 설치 및 설정: 번거로움 없이
Scalar를 실행하는 것은 식은 죽 먹기처럼 간단합니다—복잡한 레시피는 없습니다. guides.scalar.com의 문서가 아주 명확하게 설명하며, 초보자도 쉽게 시작할 수 있는 방법으로 안내해 드릴 것입니다.
단계 1: 설정 선택
Scalar는 유연합니다—호스팅 서비스로 사용할 수도 있고, 프로젝트에 임베드할 수도 있으며, 로컬에서 실행할 수도 있습니다. 초보자에게는 가장 간단한 방법: 기본 HTML 파일에 Scalar를 임베드하여 API를 다루어 보겠습니다. 아직 아무것도 설치할 필요는 없습니다—브라우저와 텍스트 편집기(VS Code 또는 메모장과 같은)만 있으면 됩니다.
단계 2: Scalar HTML 파일 만들기
- 파일 만들기: 텍스트 편집기를 열고
scalar-api.html라는 새로운 파일을 만드세요. - Scalar 코드 추가: Scalar 문서에서 이 코드 스니펫을 붙여넣으세요:
<!doctype html>
<html>
<head>
<title>내 Scalar API 참조</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<div id="app"></div>
<!-- Scalar 로드 -->
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
<!-- Scalar 초기화 -->
<script>
Scalar.createApiReference('#app', {
url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
proxyUrl: 'https://proxy.scalar.com'
})
</script>
</body>
</html>
3. 저장하고 열기: 파일을 저장한 후, 두 번 클릭하여 브라우저에서 열어보세요(Chrome, Firefox, 상관없습니다). 짜잔—Scalar의 깔끔한 인터페이스가 로드된 샘플 API(Scalar Galaxy)를 볼 수 있습니다.
이 설정은 CDN을 사용하므로 서버나 Node.js가 필요 없습니다—발을 담그기에 완벽합니다. 저는 이렇게 해봤고, 작동하는 API 참조를 보는 데 두 분도 채 걸리지 않았습니다. 당신은 어떤가요?
단계 3: 인터페이스 탐색하기
로딩이 완료되면, Scalar는 API 끝점이 있는 사이드바, 문서가 있는 메인 패널, 그리고 테스트 영역을 보여줍니다. 이리저리 클릭해 보세요—인터랙티브합니다! 샘플 Galaxy API는 재미있지만, 곧 여러분의 사양으로 바꿀 것입니다. 호스팅된 버전을 원하신다면 scalar.com에서 무료 계정을 등록하여 작업을 저장하세요.
Scalar를 사용한 API 문서 만들기
이제, Scalar를 사용하여 API를 문서화하는 방법을 알아보겠습니다. 할 일 목록 API를 작업 중이라고 가정해 보겠습니다—전문가처럼 보이게 할 수 있도록 소설을 쓰지 않을 것입니다.
단계 1: OpenAPI 사양 가져오기 또는 만들기
Scalar는 OpenAPI(즉, Swagger) 파일을 사랑합니다. 이는 당신의 API의 끝점, 매개변수 및 응답을 설명하는 JSON 또는 YAML 파일입니다. 하나 있나요? 좋습니다! 없다면, 간단한 파일을 만들어봅시다:
todo-api.yaml라는 파일을 만드세요:
openapi: 3.0.2
info:
title: 할 일 목록 API
version: 1.0.0
description: 작업을 관리하기 위한 간단한 API
paths:
/tasks:
get:
summary: 모든 작업 목록
responses:
'200':
description: 작업 목록
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
post:
summary: 작업 만들기
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
responses:
'201':
description: 작업 생성됨
2. 프로젝트 폴더에 저장하세요.
이것은 기본적인 사양이지만, Scalar가 멋지게 만들어 줄 것입니다.
단계 2: Scalar에 사양 로드하기
사양을 사용하려면:
- 호스팅하기(선택 사항): 우선
todo-api.yaml을scalar-api.html과 같은 폴더에 두세요. 웹 서버(예: Python의http.server)가 있는 경우, 다음을 실행하세요:
python -m http.server 8000
그럼 당신의 사양은 http://localhost:8000/todo-api.yaml에 있습니다.
- HTML 업데이트하기:
scalar-api.html에서url을 변경하세요:
Scalar.createApiReference('#app', {
url: './todo-api.yaml', // 또는 http://localhost:8000/todo-api.yaml
proxyUrl: 'https://proxy.scalar.com'
})
- 새로 고침:
scalar-api.html을 다시 열어보세요. 멋진—Scalar가 깔끔한 사이드바, 끝점 세부정보, 예시 응답으로 당신의 할 일 API를 렌더링합니다.
이제 문서가 인터랙티브합니다—/tasks를 클릭하여 GET 및 POST 세부정보를 확인해보세요. Scalar는 Python, JavaScript 등에서 코드 샘플을 자동으로 생성합니다. 제가 보기에는 제 지저분한 YAML이 얼마나 세련된지에 놀랐습니다!
단계 3: 문서 사용자 지정하기
특별한 flair를 원하신가요? Scalar의 설정을 조정해보세요:
Scalar.createApiReference('#app', {
url: './todo-api.yaml',
proxyUrl: 'https://proxy.scalar.com',
theme: 'purple', // 'kepler' 또는 'moon'을 시도해보세요
customCss: 'body { background-color: #f0f0f0; }'
})
새로 고침하면, 당신의 문서가 새로운 분위기로 빛날 것입니다. 호스팅 사용자들은 이를 docs.scalar.com에 저장할 수 있습니다.
Scalar로 API 테스트하기
여기서 Scalar는 한층 더 멋져집니다—문서뿐만 아닌, 내장된 API 클라이언트를 이용해 인터페이스에서 직접 끝점을 테스트할 수 있습니다. Postman이 필요 없습니다.
단계 1: 테스트 가능한 API 설정하기
테스트를 위해서는 라이브 API가 필요합니다. 없다면,reqres.in 같은 공용 테스트 API를 사용해 보세요. scalar-api.html을 업데이트하세요:
Scalar.createApiReference('#app', {
url: 'https://reqres.in/api/openapi.yaml',
proxyUrl: 'https://proxy.scalar.com'
})
새로 고침하면 Scalar가 ReqRes의 API 사양을 로드합니다.
단계 2: 끝점 테스트하기
- Scalar에서
GET /api/users와 같은 끝점을 찾으세요. - “Try it” 버튼을 클릭하세요(재생 아이콘처럼 보입니다).
- 매개변수(
page: 2)를 입력하거나 기본값을 유지하세요. - “Send”를 누르세요. Scalar는 CORS 문제를 피하기 위해 프록시를 통해 요청을 전송하고 응답을 보여줍니다—상태 코드, 헤더 및 JSON 데이터.
저는 GET /api/users를 테스트했고 몇 초 만에 깔끔한 사용자 목록의 JSON을 얻었습니다. 자신의 할 일 API를 사용하고 있다면, 로컬에서 호스팅하고(POST /tasks를 사용해 {"title": "Learn Scalar"}와 같은 본문으로 테스트해 보세요).
단계 3: 디버그 및 반복하기
404를 보셨나요? Scalar의 요청 패널에서 API URL이나 헤더를 재확인하세요. 클라이언트는 오류를 명확하게 표시하므로 빠르게 조정하고 재시도할 수 있습니다. UI에서 인증 토큰이나 쿼리 매개변수를 추가하세요—코드는 필요 없습니다.
왜 Scalar는 초보자의 꿈인가
Scalar가 초보자에게 빛나는 이유는:
- 쉬운 설정: HTML 파일 하나로 시작합니다.
- 아름다운 문서: 지저분한 YAML을 클릭할 수 있는 아름다움으로 변환합니다.
- 내장된 테스트: 빠른 확인을 위한 추가 도구가 필요 없습니다.
- 커뮤니티의 관심: X는 API를 위한 “동적 놀이터”에 대한 찬사를 올립니다.
Swagger UI와 비교할 때, Scalar는 신선하고 덜 투박하며, 더 나은 테스트 흐름을 제공합니다. 모든 것이 재미있게 만들어주는 쿨한 사촌 같은 존재입니다.
Scalar 성공을 위한 전문가 팁
- 작게 시작하세요: 간단한 사양을 사용하여 Scalar의 흐름을 배워보세요.
- Discord에 참여하세요: discord.gg/scalar에서 API 애호가들과 대화하세요.
- 사양 검증하기: 로드하기 전에 editor.swagger.io에 YAML을 붙여넣어 오류를 잡아보세요.
- 호스팅 사용하기: scalar.com에서 가입하여 협업 및 서브도메인을 사용하세요.
결론: 당신의 Scalar API 모험이 시작됩니다
축하합니다—당신은 이제 Scalar 슈퍼스타입니다! 상호작용하는 API 문서를 만들고, 전문가처럼 끝점을 테스트하는 등의 도구를 열었습니다. 이제 애완동물 상점 API를 문서화하거나 JSONPlaceholder와 같은 공용 API를 테스트해 보세요. Scalar 문서에는 더 많은 팁이 가득하고, 커뮤니티는 Discord에서 활발히 소통하고 있습니다. 당신의 첫 번째 API 프로젝트는 무엇인가요? 게임? 블로그 백엔드? 그리고 그 추가 API의 세련미를 위해서는 apidog.com에 들러보세요.
