Home

Stella · API 커버리지 도구

UMC PRODUCT 서버의 OpenAPI 스펙과 클라이언트 코드베이스의 Moya Router 연결 상태를 추적하는 SwiftPM 도구. 레포: UMC-PRODUCT/umc-product-stella

Stella란?

서버 OpenAPI 스펙에 정의된 엔드포인트 중 클라이언트가 실제로 Moya Router 로 연결한 것이 얼마나 되는지를 측정합니다. "어떤 API 가 아직 앱에 안 붙었는지", "각 엔드포인트의 담당자가 누구인지"를 스냅샷(coverage.json)과 HTML 리포트로 보여주는 커버리지 대시보드입니다.

• 두 산출물
  • apicov — 스캔·비교·HTML 리포트를 수행하는 CLI
  • stella — 담당자 매핑을 편집하고 API 를 눌러볼 수 있는 macOS GUI
• 패키지 루트 = 레포 루트 — 클론 직후 swift build. 별도 하위 디렉터리로 들어가지 않습니다.
• 요구 환경: macOS 15+, Swift 6 툴체인 (Package.swift)

문서 지도

문서	이럴 때 본다
설치와 첫 스캔	처음 클론했다. 빌드하고 coverage.json 을 만들어 보고 싶다
CLI 레퍼런스	apicov scan / diff / report 의 플래그와 종료 조건을 확인하고 싶다
Stella 앱 (GUI)	GUI 로 담당자를 지정하거나 엔드포인트를 눌러 보고 싶다
매핑 YAML	authors.yml · owners.yml · overrides.yml 을 편집한다
매칭 파이프라인	매치가 왜 됐는지/안 됐는지 원리를 알고 싶다
스냅샷 스키마	coverage.json 을 다른 도구로 읽는다
소비자 레포 연동	CI 를 붙이거나 새 레포에서 Stella 를 돌린다
개발 가이드	코드를 고치거나 테스트를 돌린다
트러블슈팅	스캔이 이상하게 나온다

왜 별도 레포인가

원래 iOS 레포(umc-product-iOS)의 Stella/ 하위 디렉터리였습니다. macOS 앱(umc-product-macOS)을 개발하면서 같은 도구를 두 소비자가 공유해야 해서 독립 레포로 분리했습니다.

이 레포는 도구만 소유합니다. 커버리지 스캔 워크플로·서버 시크릿·GitHub Pages 는 소비자 레포가 각자 가집니다. 리포트도 소비자별로 따로 나옵니다 (소비자 레포 연동 참고).

레포 구조

Package.swift                 SwiftPM 매니페스트 (레포 루트)
Sources/StellaCore/           스캐너·매처·OpenAPI 파서·스냅샷 (라이브러리)
Sources/apicov/               CLI (scan · diff · report)
Sources/StellaApp/            macOS GUI (`stella`)
Sources/StellaTestSupport/    테스트 헬퍼 (샌드박스 git 레포, URL 스텁)
Tests/                        StellaCoreTests · apicovTests · StellaAppTests
Fixtures/                     테스트 리소스 (MiniOpenAPI.json · MiniRepo · 픽스처 yml)
authors.yml · owners.yml · overrides.yml   운영 매핑 (git 커밋)
*.yml.example                 매핑 파일 템플릿
scripts/build-app.sh          `.app` 번들 패키징

소비자 레포

레포	상태	비고
umc-product-iOS	지원	--app-product(레거시 AppProduct/) · --umc-app(Tuist UMCApp/) 두 프로젝트를 스캔. Router 파일 glob 은 각각 **/Router/*Router.swift · **/Data/Sources/*Router.swift
umc-product-macOS	미지원	CLI·GUI 의 프로젝트 입력이 iOS 두 프로젝트로 고정돼 있습니다. 선행 작업은 소비자 레포 연동 › macOS 지원 참고

30초 요약

swift build

export UMC_API_USER=... 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

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

자세한 설명은 설치와 첫 스캔 에 있습니다.