Getting Started

설치와 첫 스캔

요구 환경

항목	값	근거
macOS	15 이상	Package.swift 의 platforms: [.macOS(.v15)]
Swift 툴체인	6.0 이상 (개발은 6.3 사용 중)	// swift-tools-version: 6.0
git	필수	엔드포인트 작성자를 git blame 으로 뽑습니다

CI 러너는 macos-26 + Xcode 26.4 이상을 씁니다. 로컬에서는 swift --version 이 6.x 를 가리키면 됩니다.

빌드

레포 루트가 곧 패키지 루트입니다.

git clone git@github.com:UMC-PRODUCT/umc-product-stella.git
cd umc-product-stella
swift build

첫 빌드는 swift-syntax 를 컴파일하느라 몇 분 걸립니다. 두 번째부터는 캐시가 듣습니다.

swift build 는 두 실행 파일을 만듭니다.

• apicov — CLI
• stella — macOS GUI

디렉터리 배치

소비자 레포가 이 레포의 형제 디렉터리에 클론돼 있다고 가정하고 문서의 예시를 씁니다.

Project/
├── umc-product-stella/     ← 여기서 명령을 실행
├── umc-product-iOS/
└── umc-product-macOS/

첫 스캔

OpenAPI JSON 은 Basic 인증이 걸려 있으므로 환경 변수로 계정을 넘깁니다.

export UMC_API_USER=...
export UMC_API_PASS=...

swift run apicov scan \
  --openapi-url https://dev.api.umc.it.kr/docs-json \
  --auth-env UMC_API_USER:UMC_API_PASS \
  --app-product ../umc-product-iOS/AppProduct \
  --umc-app ../umc-product-iOS/UMCApp \
  --blame-root ../umc-product-iOS \
  --authors authors.yml \
  --overrides overrides.yml \
  --owners owners.yml \
  --out coverage.json

이미 받아둔 스펙 파일이 있으면 --openapi-url 대신 --openapi-file /tmp/openapi.json 을 씁니다. 이때 --auth-env 는 필요 없습니다.

성공하면 wrote coverage.json (…bytes) 가 stderr 로 찍힙니다. --out 을 빼면 JSON 이 stdout 으로 나갑니다.

경로 해석 규칙

경로 옵션마다 기준 디렉터리가 다릅니다. 여기서 헷갈리면 "파일을 못 찾는다"가 아니라 매핑이 조용히 비어 있는 결과가 나옵니다.

옵션	기준
--blame-root	현재 디렉터리. 생략하면 현재 디렉터리 자체
--app-product, --umc-app	/ 나 . 으로 시작하면 현재 디렉터리, 아니면 --blame-root 기준
--authors, --overrides, --owners, --out	항상 현재 디렉터리

--blame-root 는 git blame 을 돌릴 레포 루트입니다. 항상 소비자 레포 루트를 넘깁니다. 생략하면 Stella 레포 자신이 blame 대상이 되어 작성자가 전부 비게 됩니다.

아래 두 명령은 같은 결과를 냅니다.

--blame-root ../umc-product-iOS --app-product ../umc-product-iOS/AppProduct
--blame-root ../umc-product-iOS --app-product AppProduct

리포트 보기

swift run apicov report coverage.json --out coverage.html
open coverage.html

자체 완결형 HTML 한 장이 나옵니다. 외부 CSS·JS 를 불러오지 않으므로 그대로 Pages 에 올리거나 슬랙에 첨부해도 됩니다. 섹션은 프로젝트별 커버리지 · 담당자 · 담당자별 엔드포인트 · 엔드포인트 · 매치 안됨 다섯 개입니다.

변화 비교

swift run apicov diff old-coverage.json coverage.json

두 스냅샷 사이에서 새로 연결된 엔드포인트와 끊긴 엔드포인트를 stdout 으로 출력합니다.

GUI 실행

swift run stella

.app 번들로 만들고 싶으면 개발 가이드 › .app 패키징 을 보세요. GUI 사용법은 Stella 앱 에 있습니다.

GUI 를 처음 띄우면 프로젝트·매핑 경로가 비어 있거나 엉뚱한 곳을 가리킵니다. 기본값이 분리 전 디렉터리 배치를 가정하기 때문입니다. 설정 화면에서 한 번 지정하면 그 뒤로는 유지됩니다.