md-spec-parser

마이데이터 스펙 문서를 파싱하여 정형 데이터(json 등)로 변환하는 Kotlin 유틸리티

---

Quickstart

요구 사항

• JDK 21

빌드 및 실행

git clone https://github.com/myddev/md-spec-parser
cd md-spec-parser

./gradlew clean build
./gradlew runMain \
  -PinputMainDoc=assets/v251001/main-spec.html \
  -PinputAuthDoc=assets/v251001/auth-spec.html \
  -PinputCsv=assets/v251001/api-id-code-mapping.csv \
  -PoutputJson=opt/md-spec.json

출력 파일 확인

cat opt/md-spec.json

직접 input 파일 생성

html

1. LibreOffice 사용(권장)
   1. LibreOffice 및 H2Orestart 설치
   2. GUI 혹은 CLI에서 스펙 파일을 HTML로 변환

   soffice.exe --headless --convert-to html spec.hwp

2. 아래아한글에서 docx로 변환, Word에서 html로 내보내기
   • 아래아한글에서 바로 html로 변환하면 정상적으로 변환되지 않습니다.

---

출력(JSON) 개요

예시 전문은 최신 릴리즈를 참고하세요.

SyntheticApiSpecV1:
  apiCode: string?                 # 은행-003
  apiId: string                    # BA03
  apiName: string                  # 수신계좌 추가정보 조회
  version: string                  # v2
  industry: string[]?              # [bank]
  scope: string[]?                 # [bank.deposit]
  resource: string                 # /accounts/deposit/detail
  httpMethod: string               # POST
  transmissionCycle: string?       # 추가
  providerRequesters:
    - provider: string             # 은행업권 
      requester: string            # 마이데이터사업자
  description: string              # 정보주체가 보유한 계좌별 추가 정보 조회
  referenceTime: string?           # 현재 시점
  requestContentType: string       # application/json; charset=UTF-8
  responseContentType: string      # application/json; charset=UTF-8
  request: ApiSpecMessage
    - headers: ApiSpecField[]
      body: ApiSpecField[]?
      params: ApiSpecField[]?
  response: ApiSpecMessage
  errorResponse: ApiSpecMessage?

ApiSpecField:
  name: string                     # x-api-tran-id
  itemDescription: string          # 거래고유번호
  isRequired: boolean              # true/false
  type: string                     # AN(25)
  note: string                     # 거래고유번호 (첨부14 참조)
  children: ApiSpecField[]?

---

테스트

./gradlew test

테스트는 마이데이터 표준 스펙의 정합성을 확인합니다. 절대로 테스트를 통과하지 못한 Output을 신뢰하지 마세요.

---

버전/릴리스 관리

• 프로젝트 버전: build.gradle.kts의 version (Sematic Versioning 사용)
• 표준 스펙 버전 표기: spec-version.txt
  • Github CI는 spec-version.txt에 명시된 버전을 참고하여 assets/v{version}/ 디렉토리 아래에 있는 html, csv 파일들을 입력으로 사용합니다.

---

트러블슈팅

• 파일 경로 오류: 입력 3개(main, auth, csv) 중 하나라도 누락 시 실행할 수 없습니다.
• HTML 파싱 실패: 파일 인코딩/형식을 확인하세요. 샘플과 동일한 형식인지 확인하세요.
• JSON 쓰기 실패: 출력 경로의 상위 디렉터리가 없을 경우 자동 생성 시도가 이뤄집니다. 권한/경로를 확인하세요.

---

기여 방법

1. 이슈를 등록하여 버그/개선 제안
2. 브랜치 생성 후 변경 사항 반영
3. 테스트 추가/갱신 및 ./gradlew test 통과 확인
4. PR 제출 (변경 요약 및 동기 포함)

코드 스타일은 Spotless/ktfmt 설정을 따르며, 포맷에 맞지 않을 경우 빌드가 제한됩니ㄷ. ./gradlew spotlessApply로 포맷을 정리할 수 있습니다.

---

라이선스

이 프로젝트에는 Apache License 2.0이 적용되어 있습니다.

---

참고

• 표준 스펙 출처