대부분의 API 설계 튜토리얼은 마우스로 시작합니다. 시각적 편집기를 열고, 스키마를 캔버스로 드래그하고, 대화 상자를 클릭하여 필드를 추가합니다. 이는 작동하지만, 많은 팀이 실제로 제품을 출시하는 방식과는 맞지 않습니다. API 정의가 Git에 있고, 풀 리퀘스트에서 검토되며, CI를 통과한다면, 배포하는 방식과 동일하게 설계하고 싶을 것입니다: 터미널에서, 텍스트로, 스크립트화할 수 있는 명령어를 사용하여.
명령줄에서 API를 설계한다는 것은 셸을 떠나지 않고도 계약을 작성하고, 스타일 가이드에 따라 린트하며, 단일 파일로 묶고, 스텁을 생성한다는 것을 의미합니다. 모든 단계는 반복 가능합니다. 모든 단계는 파이프라인에서 실행될 수 있습니다. 그리고 AI 에이전트나 팀원이 설정을 재현해야 할 때, 클릭한 버튼을 추측하는 대신 사용자가 실행했던 동일한 명령을 실행합니다.
이 가이드에서는 두 가지 경로를 다룹니다. 첫 번째는 단일 목적 도구로 구축된 일반적인 오픈 소스 경로입니다: OpenAPI 파일을 작성하고, Spectral로 린트하며, Redocly CLI로 번들링하고, openapi-generator로 서버 스텁을 생성합니다. 다음은 Apidog CLI 경로로, 설계, 스키마, 엔드포인트 및 인증이 터미널에서 제어할 수 있는 단일 프로젝트에 함께 있습니다. 더 깊이 있는 개념적 배경을 먼저 원한다면, API 설계 방법에 대한 가이드와 REST API 설계에 대한 자세한 설명을 읽어보세요.
버튼
Apidog와 함께 진행하고 있다면, 먼저 바이너리를 다운로드하세요. 저희의 Apidog CLI 설치 가이드는 `npm install -g apidog-cli` 단계와 `apidog login --with-token` 핸드셰이크를 다루며, 완전한 Apidog CLI 가이드는 모든 명령어 그룹을 설명합니다.
일반적인 오픈 소스 경로: 작성, 린트, 번들, 생성
고전적인 CLI 설계 스택은 여러 독립적인 도구를 연결하여 사용하는 것입니다. API 정의를 버전 관리되는 OpenAPI 파일에 보관하고 각 도구를 단계별로 실행합니다. 이것이 바로 Git 기반 API 설계 워크플로이며, 진정으로 좋은 방법입니다. 그 형태는 다음과 같습니다.
OpenAPI 문서 작성
평범한 YAML 파일로 시작합니다. 특별한 편집기는 필요 없으며, 어떤 텍스트 편집기든 작동합니다. 최소한의 `openapi.yaml`은 다음과 같습니다:
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: An order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
schemas:
Order:
type: object
required: [id, status]
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
API가 커지면, 여러 파일로 분할하고 `\$ref`를 사용하여 참조합니다. 이렇게 하면 각 스키마를 독립적으로 읽고 검토할 수 있습니다.
Spectral로 린트
수기로 작성된 OpenAPI는 흐트러지기 쉽습니다. 누군가는 `operationId`를 잊어버리고, 다른 사람은 응답을 문서화하지 않고, 또 다른 사람은 자신만의 명명 규칙을 만듭니다. 린터는 검토 전에 이 모든 것을 잡아냅니다. Stoplight의 Spectral은 표준적인 선택입니다. OpenAPI용 규칙 세트를 제공하며, 사용자 지정 규칙을 작성할 수 있습니다.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral은 모든 위반 사항을 줄 번호와 심각도와 함께 출력합니다. CI에서 종료 코드를 확인하여 오류 발생 시 빌드를 실패시킬 수 있습니다. Redocly의 CLI와 vacuum도 대안을 원한다면 동일한 작업을 수행합니다. vacuum은 빠르며 Spectral 호환 린터로 사용할 수 있습니다. 어떤 것을 선택하든 요점은 동일합니다: 린팅은 독립적이고 전용 도구이며, 별도의 단계로 실행해야 합니다.
Redocly CLI로 번들링
정의가 여러 파일로 분할되면, 대부분의 다운스트림 도구는 단일의 독립적인 문서를 원합니다. Redocly CLI는 모든 `\$ref`를 해결하고 트리를 하나의 파일로 평탄화합니다.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redocly는 또한 린트(`redocly lint`) 기능과 문서 미리보기 기능을 제공하므로, 일부 팀은 스타일 검사와 번들링 모두에 사용합니다. 공식 문서에는 전체 명령어 세트가 나열되어 있습니다.
openapi-generator로 스텁 생성
깔끔하게 번들링된 사양으로 코드를 생성합니다. openapi-generator는 OpenAPI 문서를 수십 가지 언어로 서버 스텁, 클라이언트 SDK 등으로 변환합니다.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
`-g spring`을 `-g python-flask`, `-g go-server` 또는 지원되는 다른 제너레이터로 바꿔보세요. 이제 계약과 정확히 일치하는 스캐폴딩을 갖게 됩니다.
이것이 오픈 경로의 전체 과정입니다: 네 가지 도구, 네 가지 명령, 모두 스크립트 가능합니다. 대가는 연결 작업입니다. 파일 레이아웃, 린터 구성, 번들 단계, 제너레이터 구성을 직접 유지 관리해야 하며, 각 도구에는 자체적인 규칙이 있습니다. 최대한의 제어를 원하고 연결 작업에 개의치 않는다면 잘 작동합니다.
Apidog CLI 경로: 단일 프로젝트에서 설계
다른 접근 방식은 설계, 스키마, 엔드포인트, 목(mock) 및 인증을 터미널에서 구동하는 단일 프로젝트 내에 유지합니다. `apidog-cli` 바이너리는 단순한 테스트 러너가 아니라 완전한 프로젝트 리소스 CLI입니다. 데이터 모델용 `schema`, 작업용 `endpoint`, 구성용 `folder`, 인증용 `security-scheme`뿐만 아니라 `import`, `export`, `mock` 등 전체 설계 표면에 대한 명령어 그룹을 갖추고 있습니다.
솔직히 미리 말씀드리자면: Apidog는 OpenAPI를 린트하거나 스타일 가이드를 강제하지 않습니다. 그것이 Apidog의 목적이 아닙니다. 린팅이 필요하다면 파이프라인에 Spectral 또는 vacuum을 유지하십시오. Apidog는 오픈 소스도 아닙니다. 무료 티어가 있는 상용 제품입니다. Apidog는 통합된 프로젝트를 제공하여 설계 요소를 직접 조합할 필요가 없도록 합니다. API 설계 및 테스트를 위한 Swagger 대안에 대한 저희의 견해는 이러한 절충안이 합리적인 지점을 다룹니다.
먼저 설치하고 인증하세요 (토큰 설정은 설치 가이드 참조):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
모든 명령은 구조화된 JSON을 반환하며, 대부분의 응답에는 다음에 무엇을 실행해야 하는지 알려주는 `agentHints.nextSteps` 블록이 포함되어 있습니다. 정확한 플래그를 보려면 어떤 명령에든 `--help`를 추가하세요.
apidog schema로 데이터 모델 정의
설계는 데이터로 시작합니다. 재사용 가능한 `Order` 스키마는 엔드포인트가 참조하는 단일 진실 소스가 되며, 이는 원시 OpenAPI의 `components/schemas`와 동일한 개념이지만 프로젝트 리소스로 관리됩니다.
apidog schema --help
apidog schema create --project <PROJECT_ID>
출력이 JSON이기 때문에, `jq`를 통해 파이프하여 새 스키마의 ID를 가져와 다음 명령에 입력할 수 있습니다. 이미 OpenAPI 파일이 있다면, 모든 것을 다시 입력하는 대신 가져오세요:
apidog import --project <PROJECT_ID> --file openapi.yaml
`apidog import`는 OpenAPI 3.x, Swagger 2.0, Postman 및 Apidog 형식을 허용하므로, 기존 정의가 한 단계 만에 활성 프로젝트가 됩니다.
apidog endpoint로 엔드포인트 정의
모델이 준비되면, 작업을 추가합니다. `endpoint` 그룹은 엔드포인트를 생성하고 업데이트하며, 정의한 스키마와 엔드포인트를 구성하는 폴더에 연결합니다.
apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
JSON으로 엔드포인트를 나열하는 것만으로도 유용합니다. 브랜치 간에 출력을 비교하거나, 모든 경로에 예상하는 응답이 있는지 확인하는 스크립트에 입력할 수 있습니다. `folder` 명령으로 관련 엔드포인트를 그룹화하여 프로젝트가 성장하더라도 탐색하기 쉽게 유지하세요.
apidog security-scheme로 인증 정의
인증은 사후 고려 사항이 아니라 계약의 일부입니다. `security-scheme` 그룹은 클라이언트가 API 키, 베어러 토큰, OAuth 2.0 등과 같은 방법으로 인증하는 방법을 정의합니다. 이는 OpenAPI의 `components/securitySchemes`에 매핑되므로, 가져오기 및 내보내기가 깨끗하게 왕복됩니다.
apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
프로젝트 수준에서 한 번 스키마를 정의하면, 각 작업이 자체 인증을 다시 선언하는 대신 모든 엔드포인트가 이를 참조할 수 있습니다. 이것은 린터가 끊임없이 잔소리할 만한 종류의 일관성입니다.
apidog cli-schema validate로 쓰기 유효성 검사
변경 사항을 커밋하거나 프로젝트를 CI에 넘기기 전에, 리소스 정의가 잘 구성되어 있는지 확인하고 싶을 것입니다. CLI는 정의 파일을 CLI가 예상하는 스키마와 비교하여 확인하는 `cli-schema validate` 명령을 제공하므로, 잘못된 쓰기 작업이 조용히 실패하는 대신 빠르게 실패합니다.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
이 명령을 파이프라인의 보호 단계로 실행하세요: 먼저 유효성 검사를 수행한 다음 적용합니다. 0이 아닌 종료 코드는 잘못된 리소스가 프로젝트에 도달하기 전에 파이프라인을 중지합니다. 이것은 CLI 쓰기 작업의 유효성 검사이지 OpenAPI 스타일 린팅이 아닙니다. 이 두 가지는 다른 작업이며, 두 번째 작업에는 여전히 Spectral을 사용하는 것이 좋습니다.
OpenAPI로 다시 내보내기
Apidog에서 설계한 다음, 표준 아티팩트를 나머지 도구 체인에 넘깁니다. `apidog export`는 OpenAPI, HTML, Markdown 또는 Postman 형식으로 내보냅니다.
apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
이제 이식 가능한 OpenAPI 파일로 돌아왔습니다. 이를 Spectral에 린팅을 위해, openapi-generator에 스텁 생성을 위해, 또는 문서 빌드에 사용할 수 있습니다. 통합 프로젝트와 오픈 도구 스택은 상호 배타적이지 않으며, 내보내기는 그 둘 사이의 다리 역할을 합니다.
CI에 연결하기
두 경로 모두 모든 명령에 종료 코드와 텍스트 출력이 있기 때문에 파이프라인에서 빛을 발합니다. 최소한의 설계 확인 작업은 린터를 실행한 다음, 유효성을 검사하고, 번들링하는 순서로 진행될 수 있습니다:
# 스타일 위반 시 실패
spectral lint openapi.yaml
# 적용 전에 CLI 리소스 쓰기 유효성 검사
apidog cli-schema validate --file resource.json
# 다운스트림 단계를 위해 단일 아티팩트로 평탄화
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Apidog의 출력은 `agentHints.nextSteps`가 포함된 JSON이므로, 이 흐름은 AI 코딩 에이전트에서도 깔끔하게 구동됩니다. 에이전트는 구조화된 결과를 읽고, 제안된 다음 단계를 확인하고, GUI 화면을 스크래핑할 필요 없이 이를 실행합니다. 이것이 CLI에서 설계하는 주된 이유입니다: 사람이 입력하는 것은 스크립트나 에이전트도 입력할 수 있습니다.
흔한 문제점
파일 분할로 인해 다운스트림 도구가 깨집니다. 여러 $ref 파일에 걸쳐 분산된 정의는 사람에게는 좋지만 제너레이터에게는 다루기 어렵습니다. 코드를 생성하거나 문서를 게시하기 전에 항상 단일 파일로 번들링하십시오. redocly bundle이 해결책입니다.
Apidog가 린트 기능을 제공할 것이라고 기대합니다. 그렇지 않습니다. Apidog는 리소스를 관리하며, 스타일 가이드를 강제하거나 OpenAPI 규칙 위반을 표시하지 않습니다. 이를 위해서는 Spectral 또는 vacuum을 계속 사용하십시오. apidog cli-schema validate를 린터로 오해하는 경우가 많습니다. 이 명령은 OpenAPI 스타일이 아닌 리소스 구조를 검증합니다.
편집하기 전에 가져오는 것을 잊는 경우. CLI를 통해 기존 API를 편집하는 경우, 먼저 원본 정의를 프로젝트로 가져와야 합니다. 비어 있는 프로젝트를 편집하고 기존 엔드포인트가 거기에 있을 것이라고 기대하는 것은 빠르게 혼란에 빠지는 방법입니다.
인증을 한 번이 아니라 엔드포인트별로 정의하는 경우. 프로젝트 수준에서 security-scheme을 정의하고 이를 참조하세요. 모든 작업에서 인증을 다시 선언하면 계약이 흐트러지게 됩니다.
마무리
CLI에서 API를 설계하는 것은 클릭이 많은 작업을 반복 가능한 명령어 세트로 바꿉니다. Spectral로 작성, 린트, Redocly로 번들링, openapi-generator로 생성하는 오픈 경로는 완벽한 제어와 종속성 없는 환경을 제공합니다. Apidog CLI 경로는 스키마, 엔드포인트, 인증이 함께 존재하고 모든 명령이 에이전트 준비 JSON을 반환하는 통합 프로젝트를 제공합니다. 내보내기 기능은 이 둘 사이의 다리 역할을 하여 어떤 상황에서도 막히지 않도록 합니다.
팀에 맞는 경로를 선택하세요. 이미 단일 목적 도구 더미와 함께 Git에서 작업하고 있다면, 그대로 유지하고 이식 가능한 아티팩트가 필요할 때 `apidog export`를 추가하세요. 연결 작업을 유지 관리하고 싶지 않다면, Apidog를 다운로드하고 CLI를 설치하여 마우스를 만지지 않고 다음 API를 설계하세요.