Stella

Stella · API 커버리지

UMC PRODUCT API와 iOS 코드베이스(AppProduct/, UMCApp/)의 Moya Router 연결 상태를 추적하는 SwiftPM 도구. 네트워크 레이어 규칙은 Networking 참고.

Stella란?

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

• 위치: 저장소 루트의 Stella/ (독립 SwiftPM 패키지)
• 두 산출물
  • apicov — 스캔·비교·리포트를 수행하는 CLI
  • stella — 담당자 매핑을 편집하는 macOS GUI
• 스캔 대상: AppProduct/(레거시)와 UMCApp/(활성) 양쪽의 Router case
• 스냅샷 스키마: Sources/StellaCore/Snapshot/CoverageSnapshot.swift 기준

빠른 시작

cd Stella
swift build

# 서버 인증 정보(스캐너가 OpenAPI를 받아올 때 사용)
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 ../AppProduct \
  --umc-app ../UMCApp \
  --blame-root .. \
  --authors authors.yml \
  --overrides overrides.yml \
  --owners owners.yml \
  --out coverage.json

이미 받아둔 OpenAPI JSON이 있으면 --openapi-url 대신 --openapi-file /tmp/openapi.json을 사용합니다. 이 경우 인증 옵션은 불필요합니다.

서브커맨드

명령	설명
apicov scan ...	OpenAPI + 코드베이스를 스캔해 coverage.json 스냅샷 생성
apicov diff old.json new.json	두 스냅샷의 커버리지 변화 비교
apicov report coverage.json --out coverage.html	HTML 리포트 렌더링 (--out 생략 시 stdout)
swift run stella	담당자 매핑 편집용 macOS GUI 실행

HTML 리포트에는 프로젝트별 요약, 담당자 롤업, 엔드포인트 테이블, 매치 안 된 Router case가 포함됩니다.

담당자 매핑 파일

Stella/ 루트의 YAML 3종으로 표시명·담당자를 보정합니다. 각각 루트의 *.example 템플릿(overrides.yml.example 등)을 같은 이름으로 복사해 사용하고, scan 시 --overrides / --authors / --owners 옵션으로 넘깁니다. (Fixtures/는 테스트용 픽스처 디렉터리로, 운영 매핑 파일이 아닙니다.)

파일	역할
overrides.yml	자동 매칭 실패 케이스 수동 보정
authors.yml	작성자 표시명·GitHub username
owners.yml	엔드포인트별/태그별 담당자 (이메일 → authors.yml의 displayName으로 해석)

GUI ↔ owners.yml 우선순위

owners.yml이 진실의 원천(source of truth) 입니다.

• scan 또는 스냅샷 로드 시점에 owners.yml의 매핑이 GUI(UserDefaults)를 자동 동기화·덮어씀
• GUI에서의 변경은 메뉴 File → owners.yml 저장… (⇧⌘S)로 커밋하기 전까지 "pending" 상태
• 저장 전에 다시 scan을 돌리면 미저장 GUI 변경은 yml 값으로 되돌아감
• 저장 시 기존 파일의 tags: 섹션은 보존되고 endpoints: 섹션만 GUI 매핑으로 덮어써짐 — 파일을 git에 커밋해야 팀원·CI가 볼 수 있음

외부(Third-party) API 처리

UMC OpenAPI 스펙에 없는 외부 서비스 API(SK TMap, KakaoMap, FCM 등)는 unmatchedRouterCases로 잡혀 노이즈가 됩니다. 해당 Router case를 scan에 넘기는 overrides.yml에 ignore: true로 등록하면 리포트에서 제외됩니다.

- routerCase: TMapGeocodingRouter.geocode
  ignore: true
  reason: external API (SK TMap), not part of UMC OpenAPI

macOS 앱 번들로 패키징

scripts/build-app.sh
open "dist/Stella.app"

• dist/Stella.app이 생성되어 Finder 더블클릭 / Applications 드래그 가능
• ad-hoc 서명만 들어가므로 다른 맥에서 처음 열 때는 우클릭 → 열기 필요 (정식 배포에는 Apple Developer ID 서명 + notarization 별도 필요)
• --no-build 플래그로 기존 release 빌드 산출물 재사용 가능

CI / GitHub Pages

.github/workflows/api-coverage.yml이 매주 월요일 00:00 UTC, develop 푸시(스캐너·라우터 변경 시), workflow_dispatch에서 실행됩니다.

1. swift build -c release --product apicov
2. apicov scan으로 coverage.json 생성 (UMC_API_USER / UMC_API_PASS secrets 사용)
3. apicov report로 _site/index.html 렌더링
4. coverage-snapshot 아티팩트 업로드 + GitHub Pages 배포

사전 작업

• 레포 Settings → Secrets and variables → Actions 에 UMC_API_USER / UMC_API_PASS 등록
• Settings → Pages 에서 source 를 GitHub Actions 로 설정
• (선택) 실제 authors.yml / overrides.yml / owners.yml을 레포에 커밋하면 자동으로 픽업됩니다. 파일이 없으면 해당 옵션은 자동 생략됩니다.

---

관련 문서: Networking · Build & Run · 원본 가이드: 저장소 Stella/README.md