한샘글로벌은 여러 고객사의 API 가이드를 제작하고 있습니다. API 가이드는 일반적으로 메서드(Method), 엔드포인트(Endpoint/URI), 요청(Request), 응답(Response)의 순서로 구성됩니다. 메서드는 API 요청의 유형(GET, POST, PUT, DELETE 등)을 명시하고, 엔드포인트는 API가 호출되는 URL 경로를 정의합니다. 요청은 API 호출 시 필요한 파라미터와 그 속성을 상세히 설명하며, 응답은 호출 결과로 반환되는 데이터와 그 구조를 설명합니다.
API 가이드 작성은 프로젝트마다 산업군, 인증 방식, 반환 필드가 조금씩 다르지만 문서의 기본 틀은 동일하기 때문에 어떤 작성자라도 편차 없이 동일한 완성도를 확보하는 것이 핵심 과제입니다.
다시 말해, API 가이드는 API별로 파라미터만 다르고 구성은 동일한 패턴을 반복하는 경우가 많기 때문에 일관성 유지가 매우 중요합니다. 뿐만 아니라, 문서 작성 과정에서 동일한 작업이 반복되므로 작업 효율성을 높여야 하는 것도 중요한 과제 중 하나입니다.
문제 제기
위와 같은 API 가이드 특성으로 인해 다음 문제들이 발생합니다.
- 일관성 부족: 담당자별 표기법, 구조, 용어 선택의 미세한 차이로 인한 문서 전체의 통일성 저해
- 휴먼 에러: 반복적 수작업(파라미터 타입 오기, 필수 항목 누락 등)에서 비롯되는 잦은 실수
- 시간 소모: 정해진 템플릿에 맞춘 수많은 테이블 및 코드 블록 작성에 적지 않은 시간 투입
이러한 문제들은 곧 가이드를 작성하는 라이터뿐만 아니라 이 가이드를 직접 사용하는 개발자의 생산성 저하와 사용자 경험의 질적 저하로 이어질 수 있습니다.
해결책 모색: 깃허브 코파일럿을 활용한 자동화 전략
문제 제기에 대한 해결의 핵심을 ‘인적 개입 최소화’와 ‘프로세스 자동화’에 두고, 이를 위해 선택한 툴이 VS CODE 익스텐션인 GitHub Copilot(이하 코파일럿)입니다.
코파일럿은 OpenAI의 GPT 외 Google의 Gemini, Anthropic의 Claude, xAI의 Grog 등 여러 대규모 언어 모델(LLM)을 활용하여 코드 자동 완성, 생성, 디버깅 등 다양한 개발 작업을 지원하는 AI 코딩 도우미입니다. 이 도구는 Visual Studio Code와 같은 IDE에서 플러그인 형태로 사용되며, 사용자의 코드 작성 패턴을 학습하여 적절한 코드 제안을 제공합니다.
코파일럿의 여러 기능 중 API 문서화 과제에 가장 적합한 핵심 기능은 다음 2가지입니다.
- 구조화된 문서 자동 생성
- 프롬프트 내 템플릿 및 규칙을 기반으로 기존 문서를 자동으로 변환
- 컨텍스트 기반 제안
- 현재 파일과 프로젝트의 문맥을 이해하여 일관성 유지를 위한 제안
- 간단한 설명 또는 주석을 기반으로 설명 및 코드 완성 제안
위 핵심 기능을 전략적 1~2단계로 활용합니다.
곧 “1단계: 프롬프트(템플릿, 규칙) 기반 구조 변환”과 “2단계: 컨텍스트 기반 자동 완성”이라는 두 단계 프로세스로 진행하여 API 가이드를 완성합니다.
1단계에서 생성한 초안은 반복 가능한 공통 구조를 보장하고, 2단계에서는 세부 필드를 채우거나 설명할 때 일관성을 유지하여 표현 및 문맥 오류를 최소화합니다. 두 단계가 연동될수록 라이터는 검토와 품질 관리에 집중합니다.
1단계: 프롬프트(템플릿, 규칙) 이용한 구조적 문서 변환
1단계의 핵심 목표는 원문 자료를 일관된 문서 구조로 빠르게 재구성하는 것입니다. 이를 위해서는 변환 대상 문서의 구성 요소를 사전에 분해하고, 템플릿과 규칙을 명확히 정의한 뒤 프롬프트에 체계적으로 반영해야 합니다.
사전 준비
- 원문 분석: 반복되는 절, 필드, 용어의 표 정리 및 패턴 도출
- 템플릿 설계: `메서드→엔드포인트→요청→응답` 등 API 가이드 구성 순서 및 도입문, 파라미터 표 형식 등 필수 요소 고정 명시
- 규칙 수집 및 정리: 용어, 데이터 타입 표기 방식, 표 머리글, 코드 블록 언어 등의 체크리스트 또는 규칙 정의
- 프롬프트 작성: 분석 결과와 템플릿, 규칙을 결합해 프롬프트 작성
실행
- 프롬프트 실행: 준비된 프롬프트를 코파일럿에 입력해 명령
- 코파일럿 수행: 프롬프트에 따라 코파일럿이 자동 변환 수행
- 검토 및 수락: 코파일럿이 제안하는 구조화된 문서를 검토 및 수락
1단계 작업으로 API 가이드의 기본 틀과 반복되는 구조가 완성됩니다. 이후 2단계에서는 세부 내용을 채우고 문서 전반의 일관성을 강화합니다.
2단계: 컨텍스트 기반 자동 완성
2단계의 목적은 코파일럿이 현재 파일과 프로젝트 전반의 문맥을 이해하도록 해 수작업 중에도 일관성과 정확도를 유지하게 만드는 것입니다. 1단계에서 정리된 템플릿과 규칙을 기반으로 실시간 제안을 받아 반복 작업을 최소화합니다.
실시간 문맥 연속성 유지
코파일럿은 직전에 작성한 섹션과 동일 파일 내의 다른 엔드포인트를 분석해 다음에 올 내용을 추론합니다. 구조가 반복되는 API 문서에서는 한 섹션을 완성한 직후 같은 패턴의 섹션 제안을 받을 수 있습니다.
또한 파라미터 타입 미기재, 예시 JSON의 괄호 미닫힘, 누락된 필수 섹션 등 자주 발생하는 실수를 문맥상 감지해 수정안을 제공합니다. 특히 긴 테이블 작업 시 사람이 놓치기 쉬운 끝줄 정렬이나 코드 블록 닫힘을 자동으로 보정합니다.
<예> 3번 라인의 수정 패턴을 인식한 후 4~6번 라인을 동일 패턴 구조로 제안(녹색 영역)
- 필드 열 백틱(`) 추가
- 타입 열 ‘문자열’ à ‘String’로 변경
- 필수 여부 열 ‘필수’ à ‘Required’로 변경
- 필수 여부 열의 ‘선택’은 문맥에 맞춰 자동으로 ‘Optional’로 변환
용어·형식 일관성 보강
프로젝트 전반에서 사용한 용어집과 스타일 가이드를 기반으로 오타나 표현 불일치를 즉시 수정 제안합니다. `settings.json`의 `copilot.additionalSuggestions` 또는 메모 파일을 활용해 주요 단어를 정의하면 제안 정확도가 높아집니다.
<예> settings.json에 ‘member’, ‘dept’ 파라미터의 설명을 정의
문맥 파악과 간단한 주석을 기반으로 설명 및 코드 완성 제안
현재 작업 중인 파일 내에서 이미 작성한 변수 이름, 함수 시그니처(인자 및 반환 타입), 클래스 정의, 데이터 구조와 같은 패턴을 학습하고, 다음에 올 코드가 기존 코드와 문법적, 논리적으로 완벽하게 연결되도록 추론하고 제안합니다. 현재 작업 중인 파일뿐만 아니라 프로젝트 전체의 코딩 스타일(들여쓰기, 변수 명명 컨벤션 등) 및 다른 파일들의 정보도 참고합니다.
<예> 문서 문맥을 파악하여 cURL의 데이터 형식 및 내용 제안
주석이나 자연어 설명을 바탕으로, 단순한 자동 완성보다 더욱 광범위하고 지능적으로 코드 블록이나 콘텐츠를 생성합니다.
<예> <– 주석 –> 주석 내용을 파악하여 해당 언어의 코드로 제안
추가 고려 사항
추가적으로 코파일럿 챗 모드(Agent, Ask, Edit), 지원 모듈(GPT, Claude, Gemini 등의 각 여러 버전)에 따라 업무 퍼포먼스가 차이날 수 있으므로 적합한 모드와 모듈 선택도 중요합니다. 이에 대한 자세한 내용은 깃허브 코파일럿 문서 페이지(https://docs.github.com/ko/copilot)를 참조 바랍니다.
<코파일럿 챗 모드>
<코파일럿 지원 모듈>
마무리
코파일럿을 활용한 API 문서 작성 자동화 전략은 단순히 시간을 절약하는 것을 넘어, API 가이드 제작의 문제점인 일관성 부족과 휴먼 에러를 해결하는 데 초점을 맞춥니다.
1단계에서 프롬프트 기반으로 반복 가능한 구조를 확립하고, 2단계에서 컨텍스트 기반으로 세부 내용의 정확도와 일관성을 보강하는 프로세스는 문서 작성자의 인적 개입을 최소화합니다. 결과적으로 라이터는 반복적인 타이핑 작업 대신, 검토와 품질 관리에 집중할 수 있도록 합니다.
현재 이 전략은 라이터의 역량을 콘텐츠 관리에 집중할 수 있도록 한다는 점에서 상당한 효과를 보이고 있습니다. 그럼에도 생성형 AI 특성상, AI 최적화 및 정교화 등은 지속적으로 해결해야 할 과제입니다. 이러한 과제들이 성공적으로 해결된다면, 본 전략은 더욱 견고하고 확장 가능하며, 내용 일관성과 작업 효율성을 더욱 극대화할 수 있을 것으로 기대합니다.