版本：Latest(v3.0) 🔥

API Document Validation

1. API Swagger 문서 개선사항

다수 API의 Summary / Description 필드가 비어있거나 의미 없는 내용
- 예시:
  - "Summary": "modifyAdminFailCntReset" (JAVA Framwork에 의해 자동 생성)
  - Description: “” (비어 있음)
  - (아래 예시는 bw-core-auth Swagger문서)
  - (잘 구성된 Swagger 예시)
문제점:
- 의미없는 Summary로 API용도 구분이 어려움(비슷한 Summary를 가진 API 다수 존재)
- “무엇을 위해 만든 API인지”, “어떤 업무 시나리오에서 쓰이는지” 한눈에 파악 불가
- 문서 기반 협업·자동화의 가치를 활용할 수 없음 → Swagger는 있지만, 실질적으로는 구전/샘플 JSON에 의존하는 형태

이 Parameter가 “배열인지/객체인지/숫자인지/문자열인지” ALL Type JSON 트리 메타 정보(모든 요청을 받을 수 있는 형태)만 제공
- 예시: Bizapi-test-prod의 “/v1/search/dsnet/addr-avail-prod-list 외 3개 Endpoint”
문제점:
- Swagger를 보는 클라이언트 개발자 입장에서는 어떤 키/값을 넣어야 하는지는 인지 불가
- “Request 샘플 요청” , “필드 설명 요청” 등 커뮤니케이션 비용 발생

서로 다른 Swagger 파일에 동일한 경로/메서드/기능의 API가 중복 정의됨
- 예시: /v1/op/cert-sms-confirm, /v1/op/cert-sms-send가 auth와 bizapi-test-auth에 중복
문제점:
- 어떤 Swagger 파일을 신뢰해야 할지 모호
- 시간이 지나면서 한쪽 파일만 수정되는 스펙 드리프트(drift) 위험
- 동일 API 수정 시 여러 파일을 동시에 수정해야 하는 유지보수 비용

목표
- 모든 주요 API에 “사람이 이해할 수 있는” Summary/Description을 채워 넣어, 용도와 시나리오를 한눈에 파악 가능하게 함
주요 액션
- Summary: 자동 생성된 메서드명 스타일(modifyAdminFailCntReset 등)을 비즈니스 용어 기반으로 변경 (예: modifyAdminFailCntReset → 관리자 로그인 실패 횟수 초기화)
- Description: 빈 Description에 최소 1~2줄 이상의 상세 설명 추가
  - “어떤 상황에서 누구에 의해 호출되는지”
  - “핵심 파라미터/제한사항 간단 정리”
검증/운영 방식
- APIM 문서 검증으로 Summary/Description 존재 여부, 최소 길이 등을 검사
- 초기에는 Warning으로 시작(Slack 공유), 점진적으로 에러 전환
- (아래는 APIM “Check Operation Description” 적용 후, 검증 결과)
- (해당 결과 Slack 채널 통해 담당자들에게 공유)
기대 효과
- Swagger만 보고도 어떤 API를 써야 할지 선택 가능
- 이후 중복 API 통합, JsonNode 제거 작업의 기반 정보 확보

목표
- JsonNode 기반 Request Body 중, “업무 핵심 API”에 대해 최소한의 필드 계약을 Swagger에 나타냄
주요 액션
- JsonNode 사용 API 식별
  - /v1/search/dsnet/addr-avail-prod-list, /v1/search/dsnet/hq-gift-list, /v1/search/dsnet/prom-list 등
- “필요한 핵심 필드” 만 별도 스키마로 분리
- 예시: AddrAvailProdRequest 등 정의 추가
```
AddrAvailProdRequest:
  type: object
  properties:
    addrId:
      type: string
      description: "주소 ID"
    svcType:                 
      type: string
      description: "서비스 유형"
  required: [addrId, svcType]    # 핵심 파라미터 선언 
  additionalProperties: true     # 나머지 키는 아무거나 허용
```
- addrId, svcType, userId 등 필수 필드만이라도 명시
- 나머지 부가 필드는 additionalProperties: true / extra 필드 등으로 유연하게 허용
검증/운영 방식
- Spectral로 #/definitions/JsonNode에 대한 직접 참조를 Warning 처리
- 신규 API에서는 JsonNode 사용을 Warning/Error 처리하고, 반드시 구체 스키마를 사용하도록 가이드
- (아래는 APIM “Check JsonNode Schema” Ruleset 적용 후, 검증 결과)
- (해당 결과 Slack 채널 통해 담당자들에게 공유)
기대 효과
- 클라이언트 개발자가 Swagger만 보고도 어떤 키/값을 넣어야 할지 알 수 있음
- 샘플 JSON 요청 위주의 구전 문화 감소

목표
- 서로 다른 Swagger 파일에 중복 정의된 Endpoint를 식별하고, 통합/정리하여 재사용성 증가
주요 액션
- 중복 API 탐지 Rulset(생성 예정)으로 method + path 기준 중복 Endpoint 리스트 자동 추출
- 예: /v1/op/cert-sms-confirm, /v1/op/cert-sms-send 가 auth, bizapi-test-auth 두 파일에 존재
- 추후, 팀 리뷰 및 정책 결정 어떤 파일을 deprecated 처리 후 제거 할지 결정
검증/운영 방식
- CI에서 중복 Endpoint 리포트 생성 (Warning 또는 실패 기준 조직 합의)
- 신규 API는 “기존 경로 재사용 여부 확인 → 신규 생성” 흐름으로 가이드
기대 효과
- 같은 기능의 API가 여러 문서에 흩어져 있는 상황 해소
- 변경 시 “어디를 수정해야 하는지” 명확해져 유지보수 비용 감소
- 공통/공유 API 라이브러리 구축의 기반 정리