DEV Community

Cover image for CLI에서 API 설계하는 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

CLI에서 API 설계하는 방법

대부분의 API 설계 튜토리얼은 마우스로 시작합니다. 시각적 편집기를 열고, 스키마를 캔버스로 드래그하고, 대화 상자를 클릭해 필드를 추가합니다. 하지만 API 정의를 Git에서 관리하고, 풀 리퀘스트로 검토하며, CI를 통과시킨다면 설계도 배포 방식과 같아야 합니다. 즉, 터미널에서 텍스트와 스크립트 가능한 명령어로 처리해야 합니다.

지금 Apidog를 사용해 보세요

명령줄 기반 API 설계는 셸을 떠나지 않고 계약을 작성하고, 스타일 가이드로 린트하고, 단일 파일로 번들링하며, 서버 스텁을 생성하는 방식입니다. 각 단계는 재현 가능하며 파이프라인에서 실행할 수 있습니다. AI 에이전트나 팀원이 동일한 환경을 재현해야 할 때도, 클릭한 UI를 추측하는 대신 같은 명령을 실행하면 됩니다.

이 가이드에서는 두 가지 경로를 다룹니다.

  1. 일반적인 오픈 소스 경로: OpenAPI 파일 작성 → Spectral 린트 → Redocly CLI 번들링 → openapi-generator 스텁 생성
  2. Apidog CLI 경로: 스키마, 엔드포인트, 인증을 하나의 프로젝트에서 터미널로 관리

개념을 먼저 확인하려면 API 설계 방법 가이드와 REST API 설계 설명을 참고하세요.

Apidog를 사용할 경우 먼저 CLI를 설치하고 로그인하세요. Apidog CLI 설치 가이드에서는 npm install -g apidog-cli와 apidog login --with-token을 다루며, 완전한 Apidog CLI 가이드에서는 명령어 그룹을 설명합니다.

일반적인 오픈 소스 경로: 작성, 린트, 번들, 생성

전통적인 CLI 설계 스택은 독립적인 도구를 단계별로 연결합니다. API 정의는 버전 관리되는 OpenAPI 파일에 저장하고, 각 작업을 명시적으로 실행합니다. 이는 Git 기반 API 설계 워크플로에 적합한 방식입니다.

전체 흐름은 다음과 같습니다.

OpenAPI 작성 → 린트 → 번들링 → 서버 스텁 또는 SDK 생성
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

API가 커지면 파일을 분리하고 $ref로 연결하세요.

openapi/
├── openapi.yaml
├── paths/
│   └── orders.yaml
└── schemas/
    └── order.yaml
Enter fullscreen mode Exit fullscreen mode

이 구조는 스키마를 독립적으로 읽고 검토하기 좋지만, 이후 코드 생성이나 문서 도구를 사용하기 전에 단일 파일로 번들링해야 할 수 있습니다.

Spectral로 린트

수기로 작성한 OpenAPI 문서는 빠르게 일관성을 잃을 수 있습니다. 예를 들어 다음 문제가 자주 발생합니다.

  • operationId 누락
  • 응답 정의 누락
  • 팀 규칙과 다른 속성 이름
  • 오류 응답 형식 불일치

Stoplight Spectral은 OpenAPI 린팅에 널리 사용되는 CLI입니다.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectral은 위반 항목을 줄 번호와 심각도 수준과 함께 출력합니다. CI에서는 종료 코드를 이용해 오류 발생 시 빌드를 실패시킬 수 있습니다.

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

프로젝트별 규칙이 필요하다면 .spectral.yaml 파일을 추가하세요.

extends:
  - spectral:oas

rules:
  operation-operationId:
    severity: error
  info-contact:
    severity: warn
Enter fullscreen mode Exit fullscreen mode

Vacuum이나 Redocly CLI도 대안이 될 수 있습니다. 어떤 도구를 선택하든 핵심은 동일합니다. 린팅은 별도의 전용 단계로 실행해야 합니다.

Redocly CLI로 번들링

여러 파일에 분리된 OpenAPI 정의는 사람이 관리하기에는 좋지만, 많은 다운스트림 도구는 하나의 독립적인 파일을 요구합니다. Redocly CLI는 모든 $ref를 해결해 단일 문서로 번들링합니다.

npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

생성된 파일을 확인하세요.

ls dist/
# openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Redocly CLI는 린트와 문서 미리보기 기능도 제공합니다.

redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

전체 명령어는 Redocly CLI 공식 문서에서 확인할 수 있습니다.

openapi-generator로 서버 스텁 생성

번들링된 OpenAPI 문서가 준비되면 서버 스텁이나 클라이언트 SDK를 생성할 수 있습니다.

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

-g 옵션을 원하는 생성기로 바꾸세요.

# Python Flask 서버
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g python-flask \
  -o ./server

# Go 서버
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g go-server \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

이제 OpenAPI 계약과 일치하는 초기 서버 구조를 갖게 됩니다.

오픈 소스 경로의 전체 과정은 다음과 같습니다.

# 1. API 계약 검사
spectral lint openapi.yaml

# 2. 분리된 OpenAPI 파일을 하나로 번들링
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

# 3. 서버 스텁 생성
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

이 방식은 제어 범위가 넓다는 장점이 있습니다. 반면 파일 구조, 린터 규칙, 번들링 단계, 생성기 설정을 직접 관리해야 합니다.

Apidog CLI 경로: 단일 프로젝트에서 설계

다른 접근 방식은 설계, 스키마, 엔드포인트, 목(mock), 인증을 하나의 프로젝트에 유지하고 터미널에서 제어하는 것입니다.

apidog-cli는 단순한 테스트 러너가 아니라 프로젝트 리소스를 관리하는 CLI입니다. 다음과 같은 명령어 그룹을 제공합니다.

  • schema: 데이터 모델 관리
  • endpoint: API 엔드포인트 관리
  • folder: 엔드포인트 구성
  • security-scheme: 인증 방식 관리
  • import, export: 정의 가져오기 및 내보내기
  • mock: 목 관련 작업

주의할 점도 있습니다. Apidog는 OpenAPI 스타일 가이드나 규칙 위반을 린트하는 도구가 아닙니다. 린팅이 필요하다면 Spectral 또는 vacuum을 파이프라인에 유지해야 합니다. Apidog는 오픈 소스가 아니며 무료 티어가 있는 상용 제품입니다.

이러한 도구 선택의 차이는 API 설계 및 테스트를 위한 Swagger 대안에서도 확인할 수 있습니다.

먼저 설치하고 인증합니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

정확한 옵션은 각 명령어의 --help로 확인하세요.

apidog --help
apidog schema --help
apidog endpoint --help
Enter fullscreen mode Exit fullscreen mode

Apidog CLI 명령은 구조화된 JSON을 반환하며, 많은 응답에는 다음 작업을 안내하는 agentHints.nextSteps 블록이 포함됩니다.

apidog schema로 데이터 모델 정의

설계는 데이터 모델에서 시작합니다. 재사용 가능한 Order 스키마를 만들고 엔드포인트에서 이를 참조하면, 계약의 단일 진실 소스를 유지할 수 있습니다.

apidog schema --help
apidog schema create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

명령 출력은 JSON이므로 jq로 필요한 ID를 추출해 다음 작업에 연결할 수 있습니다.

apidog schema create --project <PROJECT_ID> | jq -r '.data.id'
Enter fullscreen mode Exit fullscreen mode

이미 OpenAPI 파일이 있다면 수동으로 다시 작성하지 말고 가져오세요.

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

apidog import는 OpenAPI 3.x, Swagger 2.0, Postman, Apidog 형식을 지원합니다. 기존 정의를 가져온 뒤 프로젝트 리소스 형태로 계속 관리할 수 있습니다.

apidog endpoint로 엔드포인트 정의

스키마를 준비했다면 API 작업을 추가합니다. endpoint 명령 그룹은 엔드포인트 생성, 조회, 업데이트와 폴더 연결을 담당합니다.

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

엔드포인트 목록을 JSON으로 가져오면 자동 검사에 활용할 수 있습니다.

apidog endpoint list --project <PROJECT_ID> > endpoints.json
Enter fullscreen mode Exit fullscreen mode

예를 들어 브랜치 간 변경을 비교하거나, 특정 응답 코드가 모든 엔드포인트에 정의되어 있는지 확인하는 스크립트의 입력으로 사용할 수 있습니다.

프로젝트 규모가 커지면 folder 명령으로 관련 엔드포인트를 그룹화하세요.

apidog folder --help
Enter fullscreen mode Exit fullscreen mode

apidog security-scheme로 인증 정의

인증은 나중에 붙이는 설정이 아니라 API 계약의 일부입니다. security-scheme 명령 그룹으로 API 키, 베어러 토큰, OAuth 2.0 등의 인증 방식을 프로젝트 수준에서 정의합니다.

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

이 방식은 OpenAPI의 components/securitySchemes 개념에 대응합니다. 프로젝트 수준에서 인증 방식을 한 번 정의하면, 각 엔드포인트가 같은 구성을 참조할 수 있습니다.

엔드포인트마다 인증을 반복 정의하지 마세요. 인증 설정이 분산되면 서로 다른 헤더 이름, 스코프, 토큰 형식이 생겨 계약이 쉽게 일관성을 잃습니다.

apidog cli-schema validate로 쓰기 유효성 검사

프로젝트에 변경을 적용하기 전에 리소스 정의가 CLI가 기대하는 구조인지 검증할 수 있습니다.

apidog cli-schema --help
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

CI에서는 적용 전 보호 단계로 실행하세요.

# 리소스 구조 검증
apidog cli-schema validate --file resource.json

# 검증이 통과한 경우에만 후속 적용 작업 실행
Enter fullscreen mode Exit fullscreen mode

0이 아닌 종료 코드는 잘못된 리소스가 프로젝트에 반영되기 전에 파이프라인을 중지하게 합니다.

단, 이 명령은 OpenAPI 스타일 린터가 아닙니다. cli-schema validate는 CLI 리소스 구조를 검증하고, OpenAPI 규칙이나 팀의 명명 규칙을 검사하지는 않습니다. OpenAPI 린팅은 계속 Spectral 또는 vacuum으로 처리하세요.

OpenAPI로 다시 내보내기

Apidog 프로젝트에서 설계한 결과를 표준 OpenAPI 아티팩트로 내보내 다른 도구와 연결할 수 있습니다.

apidog export \
  --project <PROJECT_ID> \
  --format openapi \
  -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

내보낸 OpenAPI 파일은 기존 도구 체인에서 그대로 사용할 수 있습니다.

# OpenAPI 규칙 검사
spectral lint dist/openapi.yaml

# 번들 생성
redocly bundle dist/openapi.yaml -o dist/openapi.bundled.yaml

# 서버 스텁 생성
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

통합 프로젝트 방식과 오픈 소스 도구 체인은 상호 배타적이지 않습니다. apidog export가 두 방식을 연결하는 다리 역할을 합니다.

CI에 연결하기

두 경로 모두 종료 코드와 텍스트 또는 JSON 출력을 제공하므로 CI에 적합합니다. 최소한의 설계 검증 파이프라인은 다음처럼 구성할 수 있습니다.

# 1. OpenAPI 스타일 위반 시 실패
spectral lint openapi.yaml

# 2. CLI 리소스 쓰기 요청 검증
apidog cli-schema validate --file resource.json

# 3. 다운스트림 도구용 단일 OpenAPI 아티팩트 생성
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

GitHub Actions에서는 다음과 같이 사용할 수 있습니다.

name: Validate API contract

on:
  pull_request:
    paths:
      - "openapi/**"
      - "resource.json"

jobs:
  validate-api:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install CLI tools
        run: |
          npm install -g @stoplight/spectral-cli
          npm install -g @redocly/cli
          npm install -g apidog-cli

      - name: Lint OpenAPI
        run: spectral lint openapi.yaml

      - name: Validate Apidog resource definition
        run: apidog cli-schema validate --file resource.json

      - name: Bundle OpenAPI
        run: redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog CLI의 JSON 출력에는 agentHints.nextSteps가 포함될 수 있으므로 AI 코딩 에이전트와의 자동화에도 사용할 수 있습니다. 에이전트는 구조화된 결과를 읽고 다음 작업을 결정할 수 있으며, GUI 화면을 분석할 필요가 없습니다.

흔한 문제점

파일 분할로 인해 다운스트림 도구가 깨집니다.

여러 $ref 파일로 나뉜 정의는 사람이 관리하기 편하지만, 코드 생성기나 문서 도구가 단일 파일을 요구할 수 있습니다. 코드를 생성하거나 문서를 배포하기 전에 번들링하세요.

redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog가 린트 기능을 제공할 것이라고 기대합니다.

Apidog는 프로젝트 리소스를 관리하는 도구이며 OpenAPI 스타일 가이드를 강제하지 않습니다. OpenAPI 규칙 검사는 Spectral 또는 vacuum으로 처리하세요.

# OpenAPI 규칙 검사
spectral lint openapi.yaml

# CLI 리소스 구조 검사
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

두 명령은 서로 다른 문제를 검증합니다.

기존 API를 가져오기 전에 빈 프로젝트를 편집합니다.

기존 OpenAPI 기반 API를 CLI로 관리하려면 먼저 프로젝트로 가져와야 합니다.

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

가져오지 않은 상태에서 빈 프로젝트를 수정하면 기존 엔드포인트가 보이지 않아 혼란이 생길 수 있습니다.

인증을 엔드포인트마다 반복 정의합니다.

인증 방식은 프로젝트 수준의 security-scheme으로 정의하고 엔드포인트에서 참조하세요. 엔드포인트별로 인증을 반복 선언하면 계약이 분산되고 유지보수가 어려워집니다.

마무리

CLI 기반 API 설계는 클릭 중심 작업을 재현 가능한 명령어 집합으로 바꿉니다.

오픈 소스 경로는 다음과 같은 흐름으로 완전한 제어를 제공합니다.

OpenAPI 작성 → Spectral 린트 → Redocly 번들링 → openapi-generator 생성
Enter fullscreen mode Exit fullscreen mode

Apidog CLI 경로는 스키마, 엔드포인트, 인증을 하나의 프로젝트에서 관리하고, 구조화된 JSON 응답을 자동화 흐름에 연결할 수 있게 합니다. 필요한 경우 OpenAPI로 내보내 기존 린터, 생성기, 문서 도구와 함께 사용하면 됩니다.

이미 Git과 단일 목적 CLI 도구를 중심으로 작업하고 있다면 현재 스택을 유지하세요. 통합 프로젝트 관리가 필요하다면 Apidog를 다운로드하고 CLI를 설치해 터미널에서 다음 API 계약을 설계해 보세요.

Top comments (0)