CLI Reference

CLI 레퍼런스 — apicov

apicov <subcommand> [options]

버전 0.1.0. 서브커맨드는 scan · diff · report 세 개입니다 (Sources/apicov/Apicov.swift).

로컬에서는 swift run apicov …, CI 처럼 릴리스 빌드가 있으면 .build/release/apicov … 로 실행합니다.

---

apicov scan

OpenAPI 스펙과 클라이언트 코드베이스를 스캔해 coverage.json 스냅샷을 만듭니다.

OpenAPI 소스 (택 1, 필수)

옵션	설명
--openapi-url <url>	스펙 JSON 을 HTTP 로 받아옵니다
--openapi-file <path>	로컬 JSON 파일에서 읽습니다

둘 다 주면 --openapi-file 이 이깁니다. 둘 다 없으면 --openapi-url or --openapi-file required 로 실패합니다.

파서는 JSON 만 받습니다. .yaml 스펙은 먼저 JSON 으로 바꿔야 합니다.

인증

옵션	설명
--auth-env USER_VAR:PASS_VAR	두 환경 변수에서 Basic 인증 값을 읽어 Authorization 헤더에 붙입니다

값은 콜론으로 나뉜 환경 변수 이름 두 개입니다. 계정 문자열을 직접 넣는 자리가 아닙니다. 변수가 비어 있거나 형식이 어긋나면 auth-env vars not set: … 로 실패합니다. --openapi-file 을 쓸 때는 무시됩니다.

스캔 대상 (하나 이상 필수)

옵션	프로젝트 key	Router 파일 glob
--app-product <path>	appProduct	**/Router/*Router.swift
--umc-app <path>	umcApp	**/Data/Sources/*Router.swift

둘 다 없으면 at least one of --app-product / --umc-app required 로 실패합니다. glob 은 옵션마다 코드에 고정돼 있어 CLI 로 바꿀 수 없습니다 (Sources/StellaCore/Pipeline/ScanConfig.swift).

나머지

옵션	기본값	설명
--blame-root <path>	현재 디렉터리	git blame 을 돌릴 레포 루트. 스냅샷의 파일 경로도 이 루트 기준 상대 경로로 기록됩니다
--overrides <path>	없음	매칭 보정 YAML
--authors <path>	없음	이메일 → 표시명 매핑
--owners <path>	없음	담당자 매핑
-o, --out <path>	stdout	스냅샷 출력 위치

세 매핑 옵션은 모두 선택입니다. 안 주면 각각 빈 매핑으로 동작합니다 — 에러가 아니라 조용히 비어 있는 결과가 나오므로 CI 에서는 파일 존재를 확인하고 붙이는 편이 안전합니다.

예시

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

# 오프라인: 받아둔 스펙으로 UMCApp 만 스캔
apicov scan --openapi-file /tmp/openapi.json --umc-app ../umc-product-iOS/UMCApp \
  --blame-root ../umc-product-iOS --out coverage.json

---

apicov report

스냅샷을 자체 완결형 HTML 한 장으로 렌더링합니다.

apicov report <snapshot> [-o|--out <path>]

인자·옵션	설명
<snapshot>	coverage.json 경로 (필수)
-o, --out	출력 HTML 경로. 생략하면 stdout

외부 CSS·JS 를 불러오지 않습니다. 검색창과 담당자 필터는 인라인 스크립트로 동작하므로 파일 하나만 올리면 됩니다.

섹션 구성 (Sources/apicov/Output/HTMLReportFormatter.swift)

1. 헤더 — 스펙 제목·버전·오퍼레이션 수·생성 시각
2. 프로젝트별 커버리지 — 프로젝트 카드. 커버리지 = matched / 전체 오퍼레이션, 85% 이상 초록 · 60% 이상 노랑 · 그 아래 빨강
3. 담당자별 엔드포인트 — 담당자별 담당 수·매치 수·매치율. owners.yml 이 비어 있으면 안내 문구만 나옵니다
4. 엔드포인트 — 전체 표. 경로·요약·operationId 검색 + 담당자 필터
5. 매치 안됨 — Router case 는 있는데 스펙에 못 붙은 항목. 하나도 없으면 섹션 자체가 빠집니다

---

apicov diff

두 스냅샷을 비교해 커버리지 변화를 stdout 으로 출력합니다.

apicov diff <old> <new>

출력 예시

== Summary delta ==
  appProduct: matched +3, missing -3
  umcApp: matched +0, missing +0

== Newly connected ==
  + [appProduct] GET /api/v1/notices

== Newly disconnected ==
  - [umcApp] POST /api/v1/attendances/check

• Summary delta — 프로젝트별 matched / missing 증감
• Newly connected — 이전엔 연결이 없었는데 지금 붙은 (프로젝트, 엔드포인트)
• Newly disconnected — 반대 방향

변화가 없는 섹션은 통째로 빠지고 Summary delta 만 남습니다.

---

실패했을 때

에러는 StellaError 로 던져지고 메시지가 stderr 에 찍힙니다 (Sources/StellaCore/Errors/StellaError.swift).

케이스	흔한 원인
openAPIHTTPStatus(401)	--auth-env 로 넘긴 환경 변수가 비었거나 계정이 틀림
openAPINetwork(…)	URL 오타, 사내망 전용 주소, 네트워크 차단
fileNotFound(…)	--openapi-file 경로가 틀림
invalidYAML(…)	매핑 YAML 의 형식 오류. 메시지에 어떤 필드가 빠졌는지 나옵니다
blameFailed(…)	blame 루트가 git 레포가 아니거나 얕은 클론

blameFailed 는 스캔을 중단시키지 않습니다. 해당 엔드포인트의 작성자만 Unknown 으로 남고 나머지는 정상 진행합니다 (Sources/StellaCore/Pipeline/Pipeline.swift).

증상별 대처는 트러블슈팅 에 정리돼 있습니다.