Mapping YAML

매핑 YAML

스캔 결과를 다듬는 파일 세 개입니다. 셋 다 선택이지만 안 넘기면 담당자·표시명·예외 처리가 통째로 빠진 결과가 조용히 나옵니다.

같은 이름이 세 곳에 있다

위치	성격	비고
루트 authors.yml · owners.yml · overrides.yml	운영본	git 에 커밋. apicov scan 에 --authors / --owners / --overrides 로 넘기고 GUI 도 이 파일을 읽고 씁니다
루트 *.yml.example	템플릿	형식 참고용. 운영본이 없으면 같은 이름으로 복사해 시작합니다
Fixtures/	테스트 리소스	Package.swift 가 .copy("../../Fixtures") 로 테스트 타깃에 번들합니다. 여기를 고쳐도 실제 스캔 결과는 바뀌지 않습니다

분리 전에는 authors.yml · owners.yml 이 iOS 레포 tools/api-coverage/ 에, overrides.yml 이 Fixtures/ 에 흩어져 있어 CI 가 파일을 하나도 찾지 못했습니다. 지금은 셋 다 레포 루트에 있습니다.

---

overrides.yml — 매칭 보정

자동 매칭이 실패한 Router case 를 손으로 처리합니다. 항목마다 강제 매핑 이나 무시 중 하나를 지정합니다.

overrides:
  # 1) 외부 API 무시
  - routerCase: TMapGeocodingRouter.geocode
    ignore: true
    reason: external API (SK TMap), not part of UMC OpenAPI

  # 2) OpenAPI 키로 강제 매핑
  - routerCase: NoticeRouter.searchNotice
    openAPI:
      method: GET
      path: /api/v1/notices/search

필드	설명
routerCase	Enum.case 형식. 점이 없으면 routerCase must be 'Enum.case' 로 실패합니다
ignore + reason	경로 매칭을 건너뛰고 "의도된 제외"로 표기. reason 생략 시 ignored
openAPI.method / openAPI.path	이 Router case 를 지정한 엔드포인트로 강제 매핑. 메서드는 GET·POST·PUT·PATCH·DELETE

ignore 도 openAPI 도 없으면 override must have either ignore:true or openAPI:{method,path} 로 실패합니다.

외부 API 처리

UMC 스펙에 없는 외부 서비스 API(SK TMap, KakaoMap, FCM 등)는 어떤 엔드포인트에도 매치되지 않아 no OpenAPI entry for … 사유로 "매치 안됨"에 잡힙니다. ignore: true 를 걸면 사유가 ignored: <reason> 으로 바뀝니다.

ignore 는 항목을 리포트에서 숨기지 않습니다. 여전히 "매치 안됨" 섹션과 unmatched 집계에 남고 사유만 "의도된 제외"로 표시됩니다. 실제 누락과 구분하려는 장치입니다.

---

authors.yml — 이메일 → 사람

git blame 이 뱉은 커밋 이메일을 사람이 읽을 이름으로 바꿉니다.

authors:
  - email: euijjang97@gmail.com
    displayName: 제옹
    github: JEONG-J

필드	필수	설명
email	✓	커밋 이메일. owners.yml 이 참조하는 키이기도 합니다
displayName	✓	리포트·GUI 에 뜨는 이름
github		GitHub username. 리포트에 @username 으로 붙습니다

• email 이나 displayName 이 빠진 항목은 에러 없이 건너뜁니다
• 이메일 비교는 대소문자를 가리지 않습니다
• 매핑에 없는 이메일은 blame 의 커밋 작성자 이름을 그대로 씁니다

---

owners.yml — 엔드포인트 담당자

"이 API 는 누가 붙이기로 했나"를 기록합니다. 코드를 실제로 누가 짰는지(blame)와는 별개입니다.

owners:
  # 태그 단위 기본 담당자
  tags:
    Notice: euijjang97@gmail.com
    Auth: euijjang97@gmail.com

  # 엔드포인트 단위 지정 — 태그보다 우선
  endpoints:
    - method: GET
      path: /api/v1/notices/{id}
      owner: another@example.com

• 우선순위는 엔드포인트 지정 > 태그 지정입니다
• path 는 OpenAPI 스펙에 적힌 경로 그대로 씁니다. {id} 같은 파라미터 이름까지 정확히 일치해야 합니다
• owner 이메일은 authors.yml 을 거쳐 표시명으로 풀립니다. 명단에 없으면 이메일이 그대로 노출됩니다
• endpoints 항목에 method / path / owner 중 하나라도 빠지면 스캔이 실패합니다

GUI 가 이 파일을 덮어쓴다

Stella 앱에서 담당자를 지정하면 endpoints: 섹션이 GUI 상태로 통째로 다시 쓰입니다. tags: 섹션은 보존되니 안심하고 손으로 편집해도 됩니다. 파일 맨 위의 # Auto-generated by Stella 주석이 그 뜻입니다. 자세한 규칙은 Stella 앱 › 담당자 편집이 파일에 반영되는 규칙 을 보세요.