Blog

Redocly CLI 사용법: Redocly 튜토리얼

Mark Ponomarev

Mark Ponomarev

9 June 2025

Redocly CLI 사용법: Redocly 튜토리얼

Redocly CLI에 대한 종합 튜토리얼에 오신 것을 환영합니다! Redocly CLI는 OpenAPI 및 Swagger 정의를 위한 강력한 올인원 명령줄 도구입니다. 전체 API 수명 주기 동안 API 설명을 구축, 관리 및 품질 검사하는 데 도움이 됩니다. 개발자, 기술 문서 작성자 또는 API 제품 관리자 등 누구에게나 유용한 도구입니다.

본 튜토리얼은 Redocly CLI를 심층적으로 다루며, 초보자부터 숙련된 사용자까지 안내하는 것을 목표로 합니다. 설치부터 사용자 정의 린팅 규칙 및 CI/CD 통합과 같은 고급 기능까지 모든 것을 다룰 것입니다. 이 튜토리얼을 마치면 Redocly CLI를 일상적인 작업 흐름에 통합하여 API 품질과 문서를 개선할 수 있습니다.

💡
아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

개발 팀이 최대한의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog는 당신의 모든 요구를 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!
button

Redocly CLI란 무엇입니까?

공식 문서에 명시된 바와 같이, Redocly CLI는 당신의 "올인원 OpenAPI 유틸리티"입니다. OpenAPI 3.1, 3.0, 2.0 (레거시 Swagger), AsyncAPI 등을 지원합니다. 다음과 같은 작업에 도움이 되도록 설계되었습니다.

이 도구는 성능과 사용자 경험을 염두에 두고 구축되었으며, 빠른 실행과 사람이 읽기 쉬운 오류 메시지를 제공합니다.

Redocly CLI를 사용하는 이유

오늘날의 API 우선 세상에서 고품질 API 정의를 유지하는 것은 매우 중요합니다. Redocly CLI는 다음을 통해 이를 달성하는 데 도움이 됩니다.

이 튜토리얼에서 다룰 내용

이 튜토리얼은 Redocly CLI를 마스터하기 위한 단계별 가이드를 제공하도록 구성되어 있습니다. 다음 내용을 다룰 것입니다.

시작해 봅시다!

챕터 1: Redocly CLI 시작하기

이 챕터는 설치부터 첫 번째 명령 실행까지 Redocly CLI 사용의 첫 단계를 안내합니다.

필수 조건

시작하기 전에 시스템에 다음이 설치되어 있는지 확인하십시오.

설치

Redocly CLI를 설치하고 사용하는 데는 몇 가지 옵션이 있습니다. 필요에 가장 적합한 옵션을 선택하십시오.

npx 사용 (빠른 사용 권장)

전역 설치 없이 Redocly CLI를 사용해 보고 싶다면 npm 패키지 실행기인 npx를 사용할 수 있습니다. 이 명령은 Redocly CLI의 최신 버전을 다운로드하여 실행합니다.

npx @redocly/cli@latest --version

어떤 redocly 명령이든 사용하려면 앞에 npx @redocly/cli@latest를 붙이기만 하면 됩니다. 예를 들어:

npx @redocly/cli@latest lint openapi.yaml

이는 CI/CD 환경에서 Redocly CLI를 사용하거나 시스템을 전역 패키지로 어지럽히고 싶지 않을 때 좋은 방법입니다.

npm을 사용한 전역 설치

정기적으로 사용하는 경우 전역 설치가 더 편리합니다. 이렇게 하면 터미널에서 redocly 명령을 직접 사용할 수 있습니다.

npm install -g @redocly/cli@latest

설치 후 다음 명령으로 버전을 확인하여 설치를 확인할 수 있습니다.

redocly --version

이제 다음과 같이 명령을 실행할 수 있습니다.

redocly lint openapi.yaml

Docker 사용

Docker를 사용하려는 경우 Redocly는 미리 빌드된 Docker 이미지를 제공합니다. 이는 도구를 로컬 환경과 격리하는 데 유용합니다.

먼저 Docker Hub에서 이미지를 가져옵니다.

docker pull redocly/cli

명령을 실행하려면 현재 작업 디렉터리(API 파일이 있는 곳)를 Docker 컨테이너에 볼륨으로 마운트해야 합니다.

docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml

이 명령에서 $PWD는 현재 디렉터리를 나타내며, 이는 컨테이너 내부의 /spec 디렉터리에 마운트됩니다. 그런 다음 /spec 경로를 사용하여 파일을 참조해야 합니다.

기본 명령 구조

Redocly CLI 사용의 기본 구조는 다음과 같습니다.

redocly [command] [arguments] [options]

--help 옵션을 사용하여 특정 명령에 대한 도움말을 언제든지 얻을 수 있습니다.

redocly lint --help

이제 Redocly CLI가 설치되었고 기본 명령 구조를 이해했으니, 강력한 기능을 살펴보겠습니다.

챕터 2: 핵심 명령 및 기능

이 챕터는 Redocly CLI의 핵심 명령을 다룹니다. API 정의를 린트하고, 관리하고, 문서화하고, 분석하는 방법을 살펴보겠습니다. 이 챕터의 예제에서는 간단한 openapi.yaml 파일을 사용합니다.

다음 내용을 포함하는 openapi.yaml 파일을 생성해 봅시다.

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

섹션 2.1: API 설명 린팅 (lint)

API 린팅은 API 정의 파일의 일관성, 정확성 및 스타일을 확인하는 프로세스입니다. API 설계 지침을 적용하고 프로덕션에 도달하기 전에 잠재적인 문제를 포착하는 데 도움이 됩니다.

기본 사용법

lint 명령은 일련의 규칙에 대해 API 정의를 확인하는 데 사용됩니다.

redocly lint openapi.yaml

기본적으로 redocly lint는 recommended 규칙 세트를 사용합니다. openapi.yaml에 문제가 있는 경우 출력은 이를 자세히 설명합니다. 예제 파일의 경우 출력은 다음과 같아야 합니다.

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

규칙 구성

Redocly CLI는 세 가지 내장 구성 가능한 규칙 세트를 제공합니다.

--extends 옵션으로 규칙 세트를 지정할 수 있습니다.

redocly lint openapi.yaml --extends=minimal

redocly.yaml 구성 파일에서 자체 사용자 정의 규칙 세트를 만들 수도 있습니다. 이는 챕터 3에서 다룰 것입니다.

출력 형식

lint 명령은 --format 옵션을 사용하여 다양한 출력 형식을 지원하며, 이는 다른 도구와 통합하는 데 매우 유용합니다.

stylish 형식을 사용하는 예:

redocly lint openapi.yaml --format=stylish

문제 무시

때로는 특정 문제를 무시해야 할 수도 있습니다. 오류 및 경고를 억제하기 위해 .redocly.lint-ignore.yaml 파일을 생성할 수 있습니다.

redocly lint openapi.yaml --generate-ignore-file

이 명령은 무시 파일을 생성합니다. lint를 다시 실행하면 이 파일에 나열된 문제가 무시됩니다. 이를 통해 린팅 프로세스를 세밀하게 제어할 수 있습니다.

섹션 2.2: bundle 및 split으로 API 설명 관리

API가 커짐에 따라 단일의 모놀리식 OpenAPI 파일을 관리하는 것은 번거로워집니다. Redocly CLI는 이를 돕기 위해 split 및 bundle 두 가지 명령을 제공합니다.

대규모 OpenAPI 파일 분할 (split)

split 명령을 사용하면 대규모 API 정의 파일을 더 관리하기 쉬운 다중 파일 구조로 분할할 수 있습니다. 구성 요소, 경로 및 예제를 별도의 파일 및 폴더로 추출합니다.

openapi.yaml을 분할해 봅시다.

redocly split openapi.yaml --outDir=split-api

이 명령은 다음과 같은 구조의 split-api 디렉터리를 생성합니다.

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

split-api의 새로운 openapi.yaml은 이제 $ref를 사용하여 외부 파일에 링크합니다.

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

이렇게 하면 API의 다른 부분을 훨씬 쉽게 관리할 수 있습니다.

여러 파일 번들링 (bundle)

bundle 명령은 split의 반대 작업을 수행합니다. 루트 API 정의 파일을 가져와 모든 로컬 $ref를 해결하여 단일 자체 포함 파일을 생성합니다. 이는 다중 파일 정의를 지원하지 않는 도구에 유용합니다.

분할된 API를 단일 파일로 다시 번들링해 봅시다.

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

bundled-api.yaml은 원래 openapi.yaml과 동일한 내용을 가질 것입니다.

역참조

bundle 명령은 모든 $ref (원격 포함)가 해결되고 해당 내용으로 대체된 완전히 역참조된 파일을 생성할 수도 있습니다.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

이는 유용할 수 있지만, 파일이 훨씬 커질 수 있고 순환 참조가 JSON 출력에 문제를 일으킬 수 있다는 점에 유의하십시오.

섹션 2.3: API 문서 생성 (build-docs)

Redocly CLI의 가장 강력한 기능 중 하나는 오픈 소스 Redoc 엔진을 사용하여 아름답고 상호 작용하는 API 참조 문서를 생성하는 기능입니다.

기본 사용법

문서를 생성하려면 build-docs 명령을 사용합니다.

redocly build-docs openapi.yaml

이렇게 하면 현재 디렉터리에 redoc-static.html 파일이 생성됩니다. 브라우저에서 열어 문서를 확인하십시오.

-o 또는 --output 옵션으로 다른 출력 파일을 지정할 수 있습니다.

redocly build-docs openapi.yaml -o my-api-docs.html

출력 사용자 정의

--theme.openapi 옵션을 사용하여 문서의 모양과 느낌을 사용자 정의할 수 있습니다. 이를 통해 색상, 글꼴을 변경하고 검색 바와 같은 UI의 일부를 비활성화할 수도 있습니다.

예를 들어, 검색 바를 비활성화하려면:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

사용 가능한 모든 테마 옵션은 공식 Redocly 문서에서 찾을 수 있습니다.

더 많은 제어를 위해 자체 Handlebars 템플릿을 제공하여 문서를 렌더링할 수 있습니다. 이는 HTML 출력을 완전히 사용자 정의할 수 있는 고급 기능입니다.

섹션 2.4: API 통계 가져오기 (stats)

stats 명령은 경로, 작업, 스키마 등의 수와 같은 API 정의에 대한 유용한 메트릭을 제공합니다.

통계 가져오는 방법

API에 대한 통계를 얻으려면 간단히 다음을 실행합니다.

redocly stats openapi.yaml

기본 출력은 stylish 형식입니다.

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

다양한 형식

lint 명령과 마찬가지로 stats는 --format 옵션으로 다양한 출력 형식을 지원합니다. json 및 markdown 형식은 특히 유용합니다.

redocly stats openapi.yaml --format=json

이는 통계를 다른 도구나 대시보드로 가져오는 데 유용합니다.

redocly stats openapi.yaml --format=markdown

이는 Markdown 테이블을 생성하며, 보고서나 다음 챕터에서 볼 GitHub Actions 요약에 사용하기에 적합합니다.

챕터 3: 고급 주제

이 챕터에서는 강력한 구성 파일과 CI/CD 파이프라인과의 통합을 포함하여 Redocly CLI의 일부 고급 기능에 대해 자세히 알아보겠습니다.

구성 파일 (redocly.yaml)

명령줄에서 Redocly CLI를 완전히 사용할 수 있지만, redocly.yaml 구성 파일을 사용하면 구성을 한 곳에 저장하여 명령을 더 짧게 만들고 구성을 재사용할 수 있습니다.

프로젝트 루트에 redocly.yaml 파일을 생성해 봅시다.

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

구성 파일 구조

API 별칭 사용

apis 섹션이 구성되면 이제 명령에서 파일 경로 대신 main 별칭을 사용할 수 있습니다.

redocly lint main
redocly stats main
redocly build-docs main

이는 프로젝트에 여러 API가 있을 때 특히 유용합니다. 인자 없이 redocly lint를 실행하면 apis 섹션에 정의된 모든 API를 린트합니다.

지속적 통합 (CI)

Redocly CLI를 CI/CD 파이프라인에 통합하는 것은 API 품질 검사를 자동화하는 환상적인 방법입니다. GitHub Actions와 함께 사용하는 방법의 예는 다음과 같습니다.

.github/workflows/redocly.yaml 파일을 생성합니다.

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

이 GitHub Actions 워크플로우는 다음을 수행합니다.

  1. main 브랜치에 대한 모든 푸시 및 풀 리퀘스트에서 트리거됩니다.
  2. 코드를 체크아웃합니다.
  3. Node.js 및 Redocly CLI를 설치합니다.
  4. github-actions 형식으로 lint 명령을 실행합니다. 이렇게 하면 풀 리퀘스트에 문제가 자동으로 주석으로 표시됩니다.
  5. markdown 형식으로 stats 명령을 실행하고 출력을 작업 요약에 추가하여 실행할 때마다 좋은 보고서를 제공합니다.

이는 API 정의가 항상 좋은 상태를 유지하도록 보장하는 강력한 방법입니다.

챕터 4: 실용적인 예제: 완전한 워크플로우

이 마지막 챕터에서는 배운 모든 것을 종합하여 완전하고 실용적인 워크플로우를 단계별로 살펴보겠습니다. 다음을 수행할 것입니다.

  1. 다중 파일 API 정의로 프로젝트 구조를 생성합니다.
  2. redocly.yaml 구성 파일을 생성합니다.
  3. 사용자 정의 구성을 사용하여 API 정의를 린트합니다.
  4. API를 단일 파일로 번들링합니다.
  5. API 문서를 생성합니다.

1. 프로젝트 설정

프로젝트를 위한 새 디렉터리를 만들고 파일 구조를 설정해 봅시다.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

이제 분할된 API 파일을 만들어 봅시다.

openapi/components/schemas/Pet.yaml:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml:

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (우리의 주요 진입점):

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. redocly.yaml 생성

이제 redocly-petstore 디렉터리의 루트에 구성 파일을 만들어 봅시다.

redocly.yaml:

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

이 구성에서 API에 대한 petstore@v1 별칭을 정의하고 일부 사용자 정의 린팅 규칙을 추가했습니다.

3. API 린트

이제 새 구성을 사용하여 API를 린트해 봅시다.

redocly lint petstore@v1

API가 새 규칙을 모두 준수하지 않기 때문에 일부 오류와 경고가 표시될 것입니다. 예를 들어, 설명이 있는 태그가 없습니다. 이는 자체 API 스타일 가이드를 적용하는 방법을 보여줍니다.

4. API 번들링

다음으로, 다중 파일 API를 단일 배포 가능한 파일로 번들링해 봅시다.

redocly bundle petstore@v1 -o dist/petstore.yaml

이렇게 하면 완전히 해결된 API 정의가 포함된 petstore.yaml 파일이 있는 dist 디렉터리가 생성됩니다.

5. 문서 생성

마지막으로 API 문서를 생성해 봅시다.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

이렇게 하면 dist/petstore-docs.html이 생성됩니다. 브라우저에서 이 파일을 열어 아름답고 상호 작용하는 API 문서를 확인하십시오.

이제 완성되었습니다! 구조화된 다중 파일 API 정의부터 번들링된 파일 및 전문 문서까지, Redocly CLI로 관리되는 완전한 워크플로우입니다.

결론

이 튜토리얼에서는 Redocly CLI를 심층적으로 살펴보았습니다. 설치 및 핵심 명령의 기본부터 시작하여 구성 및 CI 통합과 같은 고급 주제로 이동했으며, 마지막으로 완전하고 실용적인 워크플로우를 단계별로 살펴보았습니다.

이제 Redocly CLI를 사용하여 다음을 수행하는 방법에 대한 확실한 이해를 갖게 되었을 것입니다.

Redocly CLI는 API 개발 워크플로우를 크게 개선할 수 있는 다재다능하고 강력한 도구입니다. 기능을 더 자세히 살펴보고 프로젝트에 통합해 보시기 바랍니다.

추가 자료

이 튜토리얼을 따라주셔서 감사합니다. 즐거운 API 구축 되세요!

💡
아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

개발 팀이 최대한의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog는 당신의 모든 요구를 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!
button

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드