API 매뉴얼을 .docx에서 웹 페이지로 전환한 이야기

배경

가맹점이 새로 연동을 시작할 때마다 운영팀이 Word 파일(.docx)로 API 매뉴얼을 전달하고 있었다.

버전이 올라갈 때마다 파일을 다시 만들어서 다시 보내고, 가맹점 쪽에서는 어떤 버전을 받은 건지 헷갈린다. 최신인 줄 알고 연동했는데 구버전이라 문의가 들어오는 일도 있었다.

직접 연동 문의 대응을 하면서 이 비효율을 체감하고 있었고, 시간이 생긴 김에 개선 방안을 직접 만들어봤다.

---

기존 방식의 문제

운영팀이 .docx 작성 → 이메일 첨부 → 가맹점 수신 → 버전 혼동

문제	설명
반복 작업	가맹점마다 파일을 따로 전달해야 한다
버전 관리 불가	가맹점이 받은 파일이 최신인지 확인할 방법이 없다
수정 시 재배포	문서 수정 시 모든 가맹점에 다시 보내야 한다

---

구현

기존 API 매뉴얼 .docx 를 기반으로 정적 API 문서 웹 페이지를 직접 만들었다.

• 다크 테마 + 사이드바 네비게이션
• Syntax highlighting
• Request/Response 탭 전환
• Stripe, GitHub API Docs 스타일 참고

Before: .docx 파일 이메일 전달 → 버전 혼동
After:  URL 하나 공유 → 언제든 접속 → 항상 최신 문서

---

배포 구성

정적 HTML이라 배포 구성이 단순하다.

서버 (Nginx)
  └── /var/www/api-docs/index.html

• Nginx에서 정적 파일 서빙
• 문서 업데이트 시 index.html 하나만 교체하면 전체 가맹점에 즉시 반영
• 기존 서버에 포트 하나만 추가하면 되기 때문에 인프라 부담 없음

---

기대 효과

1. 운영팀 리소스 절감 — 가맹점마다 파일을 만들어 보내는 반복 작업 제거
2. 가맹점 경험 개선 — URL 하나로 언제 어디서든 최신 문서 확인 가능
3. 버전 관리 일원화 — 서버 파일 하나만 교체하면 전체 반영

---

정리

업무 중 반복적으로 발생하는 비효율을 발견하고, 직접 대안을 설계하고 구현까지 해본 경험이다.

정적 HTML + Nginx라는 단순한 구성이지만, 운영 프로세스 개선이라는 관점에서 의미 있는 작업이었다.