Cloudflare Forge로 SDK·CLI·API 문서를 자동 생성하려면 OpenAPI 명세를 입력하고 필요한 변환기와 출력 경로를 설정한 뒤 Forge 명령을 실행하면 된다. 이미 OpenAPI를 관리하고 있는 프로젝트라면 API 구현을 바꾸지 않고도 생성 파이프라인을 연결할 수 있다.
다만 설치만 마치면 모든 결과물이 한 번에 완성되는 도구로 이해하면 곤란하다. 생성 대상에 맞는 플러그인, Docker 실행 환경, 재생성 정책, CI 검증 순서까지 함께 설계해야 수동 수정이 사라지고 운영 가능한 자동화가 된다.
📌 핵심 요약
- Forge는 2026년 9월 28일 공개된 Apache 2.0 기반의 오픈소스·플러그형 생성 파이프라인이다.
- 현재 핵심 입력 형식은 OpenAPI이며 SDK, CLI, 최종 API 문서와 작업 매핑 파일을 만들 수 있다.
- 생성 디렉터리는 직접 수정하지 않고 OpenAPI와 설정만 변경해야 재생성 때 코드가 덮어써지는 문제를 피할 수 있다.
Cloudflare Forge란 무엇이며 기존 OpenAPI 생성기와 무엇이 다른가
Cloudflare Forge는 API 정의를 SDK, CLI, 문서 같은 여러 산출물로 변환하는 생성 파이프라인이다. 하나의 고정된 코드 생성기가 아니라 입력을 처리하고 결과물을 만드는 변환기를 조합할 수 있는 플러그형 구조라는 점이 핵심이다. 라이선스는 Apache 2.0이어서 사내 도구나 상용 프로젝트에서도 라이선스 조건을 확인한 뒤 활용할 수 있다.
Cloudflare가 이 도구를 만든 배경에는 API 규모가 있다. Cloudflare 공식 발표에 따르면 자사 API에는 3,500개가 넘는 작업이 포함돼 있다. 이 정도 규모에서는 SDK와 문서를 사람이 따로 관리할수록 명세, 메서드 이름, 설명이 서로 달라질 가능성이 커진다.
3,500개 이상
Cloudflare API가 포함하는 작업 수 · Cloudflare 공식 발표, 2026년
Forge는 각 API 저장소의 CI에서 변경된 OpenAPI를 린트하고 CLI·문서·SDK 미리보기를 만들도록 설계됐다. 따라서 단순히 코드를 생성하는 데서 끝나지 않고, API 변경이 실제 개발자 경험에 어떤 영향을 주는지 병합 전에 검토하는 흐름까지 포괄한다.
2026년 10월 기준으로 공식적으로 확인되는 핵심 입력은 OpenAPI다. 다른 명세 형식을 바로 지원한다고 단정해서는 안 되며, AsyncAPI나 GraphQL 스키마를 사용한다면 OpenAPI 변환 가능성과 별도 플러그인 제공 여부부터 확인해야 한다.
기존 OpenAPI 프로젝트에 Forge 설치하고 설정하는 절차
가장 안전한 연결 순서는 현재 명세를 먼저 검증한 다음 별도의 생성 디렉터리를 지정하는 것이다. 애플리케이션 소스와 생성 코드를 처음부터 섞으면 삭제 범위와 코드 리뷰가 불명확해진다.
- OpenAPI 파일을 기준점으로 정한다. 저장소에 여러 명세가 있다면 배포에 실제 사용하는 번들 파일을 선택한다.
- Forge 코어를 설치한다. pnpm 기반 프로젝트에서는 공식 안내 명령인
pnpm add @cloudflare/forge를 사용한다. - 필요한 생성기를 추가한다. TypeScript SDK가 필요하다면 개발 의존성으로
pnpm add --save-dev @cloudflare/forge-transformer-sdk-ts를 설치한다. - 출력 경로를 분리한다. 예를 들어 저장소 루트의
generated를 전용 결과 디렉터리로 사용한다. - 최초 생성 후 변경 파일을 검토한다. SDK 메서드명, 요청·응답 타입, 최종 명세와 매핑 파일이 의도대로 만들어졌는지 확인한다.
번들된 명세 파일이 openapi.json이라면 기본 실행 형태는 다음과 같다.
pnpm exec forge openapi.json --out ./generated앞 단계의 번들러가 표준출력으로 명세를 전달한다면 입력 파일명 대신 하이픈을 지정한다. 이 방식은 임시 OpenAPI 파일을 만들지 않고 파이프라인을 연결할 때 유용하다.
명세를 출력하는 명령 | pnpm exec forge - --out ./generated패키지 버전에 따라 설정 스키마와 사용 가능한 변환기 이름이 달라질 수 있으므로 블로그 예제만 복사하기보다 설치된 버전의 CLI 도움말과 Cloudflare Forge 저장소를 함께 확인하는 편이 안전하다.
Cloudflare Forge 최신 설치 명령과 지원 변환기 자세히 보기
SDK·CLI·API 문서 생성 결과와 디렉터리 구조 확인법
생성 명령이 정상 종료되면 출력 디렉터리에서 최종 OpenAPI 문서, 생성된 SDK 소스, API 작업과 SDK 메서드의 연결 정보를 확인할 수 있다. 실제 하위 경로는 활성화한 변환기와 버전에 따라 달라질 수 있지만, 산출물의 역할은 구분해서 이해해야 한다.
| 생성물 | 확인할 내용 | 운영 용도 |
|---|---|---|
| 최종 OpenAPI 문서 | 번들링·변환 이후 경로, 스키마, 메타데이터 | 문서와 후속 생성 작업의 기준 |
| SDK 소스 | 클라이언트, 타입, API별 메서드와 직렬화 코드 | 패키지 빌드·배포 및 미리보기 |
sdk-map.json |
OpenAPI 작업과 생성된 SDK 메서드의 대응 관계 | 누락 탐지와 변경 영향 분석 |
| CLI·문서 결과 | 활성 플러그인별 명령, 설명, 예제와 탐색 구조 | 사용자용 명령 도구와 API 포털 |
sdk-map.json은 특히 중요하다. 생성 파일 개수만 확인하면 특정 API 작업이 빠졌거나 예상과 다른 메서드로 변환된 사실을 놓칠 수 있지만, 매핑 정보를 비교하면 OpenAPI의 operationId 변경이 SDK 공개 인터페이스에 미친 영향을 추적하기 쉽다.
샘플 명세로 검증할 때는 최소한 조회용 GET, 본문이 있는 POST, 경로 매개변수, 오류 응답, 재사용 스키마를 포함하는 편이 좋다. 이 다섯 요소가 있어야 단순 파일 생성 여부를 넘어 타입과 메서드 서명이 실무 API에서도 유지되는지 판단할 수 있다.
SDK·CLI·API 문서 생성 결과와 디렉터리 구조 확인법 바로가기
Forge 문서 설정 구조와 astro-fern·fern-forge 역할
Cloudflare의 문서 생성 구성은 하나의 패키지에 모두 들어 있지 않다. 공식 저장소 기준으로 렌더링, Forge 메타데이터 변환, 공통 설정, 실제 사이트가 역할별로 나뉜다.
- astro-fern: Astro 환경에서 문서 화면을 구성하는 영역이다.
- fern-forge: Forge 메타데이터를 검증하고 Fern이 소비할 형태로 변환한다.
- @cloudflare/fern-config: 여러 문서 프로젝트가 공유하는 Fern 설정과 워크스페이스 준비 기능을 제공한다.
- docs-site: 앞의 구성 요소를 소비해 실제 문서 사이트를 만든다.
이 구조는 생성기 설정과 사이트 표현 계층을 분리한다는 의미가 있다. API 설명이나 스키마 같은 내용은 OpenAPI에 두고, 브랜드 탐색 구조와 페이지 렌더링은 문서 사이트에서 관리하면 같은 명세로 SDK와 문서를 만들면서도 각 결과물의 책임을 명확히 유지할 수 있다.
설정 파일을 수정할 때도 같은 기준이 필요하다. 메서드명이나 요청 타입 문제를 문서 템플릿에서 우회하지 말고 원본 명세의 operationId, 태그, 스키마 이름부터 점검해야 한다. 반대로 내비게이션이나 시각적 구성은 API 명세에 억지로 넣기보다 문서 계층에서 처리하는 편이 유지보수에 유리하다.
Forge 문서 설정 구조와 astro-fern·fern-forge 역할 신청하기
Docker 빌드 오류와 Forge 생성 실패를 해결하는 순서
전체 SDK 생성에는 Docker가 필요하다. 명세 린트는 통과하지만 생성 빌드가 실패한다면 소스 코드를 먼저 고치기보다 Docker 데몬이 실행 중인지, 현재 계정이 접근할 수 있는지, CI 러너에 Docker가 제공되는지부터 확인해야 한다.
- 명령 인식 여부:
pnpm exec forge --help가 실행되는지 확인한다. 실행 파일을 찾지 못한다면 설치 위치와 워크스페이스 의존성부터 점검한다. - 입력 파일 여부: CI의 작업 디렉터리와
openapi.json경로를 확인한다. 로컬 상대 경로가 CI에서도 같다고 가정하면 파일 없음 오류가 나기 쉽다. - Docker 연결 상태: 로그에
Cannot connect to the Docker daemon이 보이면 Docker 실행 여부와 소켓 권한을 확인한다. - 명세 검증: 중복되거나 누락된
operationId, 해석할 수 없는 참조, 잘못된 스키마를 수정한다. - 저장소 검증: 공식 저장소에서 안내하는
pnpm test,pnpm typecheck,pnpm check를 차례로 실행한다.
출력 디렉터리 권한도 자주 놓치는 지점이다. 이전 빌드가 다른 사용자 권한으로 파일을 만들었거나 읽기 전용 캐시를 복원했다면 생성기가 결과물을 교체하지 못한다. CI에서는 매 실행마다 깨끗한 출력 경로를 준비하고, 캐시는 의존성에만 제한적으로 적용하는 구성이 안정적이다.
Docker 빌드 오류와 Forge 생성 실패를 해결하는 순서 지원하기
재생성 덮어쓰기 방지와 CI 자동화 실전 설계
생성된 SDK 파일을 직접 수정하면 다음 실행에서 변경 내용이 사라질 수 있다. 가장 중요한 원칙은 생성물은 언제든 다시 만들 수 있는 결과로 취급하고, 사람이 작성한 코드는 별도 디렉터리에 두는 것이다.
인증 처리나 재시도 정책처럼 프로젝트 고유 기능이 필요하다면 생성된 메서드 내부를 수정하지 말고 래퍼, 확장 모듈, 미들웨어 계층으로 분리한다. 생성기가 제공하는 공식 훅이나 템플릿 확장 지점이 있다면 이를 먼저 사용하고, 그렇지 않다면 생성 패키지를 소비하는 상위 패키지에서 기능을 추가하는 편이 안전하다.
CI에서는 OpenAPI 변경이 있는 풀 리퀘스트마다 의존성 설치, 명세 린트, Forge 생성, 테스트와 타입 검사, 생성 결과 차이 확인 순서로 실행할 수 있다. 생성물을 저장소에 커밋하는 정책이라면 재생성 후 git diff --exit-code로 누락된 갱신을 탐지할 수 있다. 커밋하지 않는 정책이라면 빌드 아티팩트로 보관해 리뷰어가 SDK·CLI·문서 미리보기를 확인하게 만드는 방식이 맞다.
전문가 관점에서 Forge의 가치는 생성 속도보다 변경 통제에 있다. 3,500개가 넘는 작업을 다루는 Cloudflare처럼 API 표면이 커질수록 “생성이 성공했는가”보다 “어떤 작업이 어떤 SDK 메서드로 바뀌었는가”가 더 중요한 품질 지표가 된다. 이때 sdk-map.json과 PR 미리보기를 함께 활용하면 공개 인터페이스의 의도하지 않은 변경을 병합 전에 찾을 수 있다.
도입 초기에는 모든 언어와 문서를 한꺼번에 전환하기보다 TypeScript SDK 한 종류와 작은 샘플 명세로 시작하는 편이 현실적이다. 결과가 안정되면 실제 번들 OpenAPI, CLI, 문서 사이트 순으로 범위를 넓히고, 마지막에 배포 자동화를 연결하면 문제 발생 구간을 빠르게 분리할 수 있다.
Forge 저장소의 최신 설정 예제와 CI 검증 절차 확인하기
정리하면 Cloudflare Forge 도입의 출발점은 정확한 OpenAPI 명세이며, 성공 기준은 파일이 생성됐다는 사실만이 아니다. 출력 디렉터리를 소스와 분리하고, Docker 환경을 고정하며, 매핑 결과와 변경 차이를 CI에서 검사해야 SDK·CLI·API 문서가 같은 계약을 지속적으로 따르게 된다.