기술 문서(API 문서) 설명 글자수 기준

Stripe의 API 문서는 개발자 커뮤니티에서 "최고의 기술 문서" 예로 자주 언급된다. Stripe 문서의 특징은 엔드포인트 설명이 짧고 명확하며, 코드 예시가 풍부하다는 점이다. 긴 설명 대신 바로 실행 가능한 코드 예시가 더 효과적인 경우가 많다.

핵심 답변

API 엔드포인트 설명은 50-150자(1-3문장)가 권장됩니다. 파라미터 설명은 30-80자로 간결하게 작성합니다. Stripe·Twilio 등 유명 API 문서를 분석하면 설명을 짧게 유지하고 코드 예시로 보완하는 패턴을 따릅니다.

API 문서 요소별 권장 글자수

좋은 API 문서의 특징

1. 설명보다 예시

http
POST /v1/users
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepass123"
}

코드 예시 하나가 100자 설명보다 효과적이다.

2. 모든 파라미터 명시

필수(required)/선택(optional) 구분을 명확히 한다.

3. 에러 응답 포함

성공 케이스만큼 에러 케이스가 중요하다.

json
{
  "error": {
    "code": "invalid_email",
    "message": "이메일 형식이 올바르지 않습니다."
  }
}

4. 버전 정보

API 버전(v1, v2)과 변경 이력(Changelog)을 문서에 포함한다.

기술 문서 도구

• OpenAPI/Swagger: REST API 명세 자동화
• Notion: 내부 문서화
• GitBook: 공개 기술 문서
• Docusaurus: 오픈소스 문서 사이트

OpenAPI 명세를 사용하면 코드에서 문서를 자동 생성할 수 있어 문서와 코드 불일치를 방지한다.

실전 적용 가이드: API 문서 작성 순서

1단계: 엔드포인트 목록 먼저 작성

설명보다 엔드포인트 목록(URL, HTTP 메서드, 한 줄 설명)을 먼저 완성합니다. 개발자는 목록을 훑으며 필요한 엔드포인트를 찾고, 그 후 세부 사항을 읽습니다.

2단계: 요청/응답 예시 코드 추가

각 엔드포인트에 실제로 실행 가능한 요청 예시(curl 또는 언어별 코드)와 응답 JSON을 추가합니다. 이 부분이 개발자가 가장 먼저 복사해서 사용하는 부분입니다.

3단계: 에러 코드 테이블 작성

흔히 발생하는 에러 코드와 원인, 해결 방법을 테이블로 정리합니다. 에러 문서가 없으면 개발자는 문제 발생 시 지원 채널에 문의해야 합니다.

4단계: 설명 텍스트는 마지막에 보완

코드 예시, 에러 코드, 파라미터 테이블이 완성된 후 설명 텍스트를 보완합니다. 코드로 설명되지 않는 비즈니스 로직·제약 사항(예: "하루 1,000건 요청 제한")을 텍스트로 추가합니다.

전/후 예시: 파라미터 설명

전 (모호하고 긴 설명):

user_id: 이 파라미터는 해당 작업을 수행할 사용자의 고유 식별자를 나타내며, 시스템에서 부여된 정수형 값을 사용해야 합니다.

후 (간결하고 명확):

user_id (integer, required): 사용자 고유 ID. /v1/users에서 반환된 값.

(74자 → 30자, 동일한 정보 전달)

체크리스트

• [ ] 각 엔드포인트에 한 줄 설명(50-100자)이 있는가
• [ ] 요청 예시 코드 블록이 실제 실행 가능한가
• [ ] 파라미터에 타입(type)과 필수 여부(required/optional)가 명시되어 있는가
• [ ] 주요 에러 코드와 해결 방법이 문서화되어 있는가
• [ ] API 버전과 변경 이력(Changelog)이 포함되어 있는가

자주 묻는 질문

Q. OpenAPI(Swagger)로 자동 생성된 문서와 수동 작성 문서 중 어느 것이 나은가요?

OpenAPI는 파라미터 테이블과 예시 요청/응답을 자동 생성해 유지 관리가 편합니다. 그러나 비즈니스 로직 설명, 사용 예시, 개념 가이드는 수동으로 작성해야 합니다. Stripe처럼 뛰어난 API 문서는 OpenAPI 자동 생성 + 수동 가이드를 결합합니다.

Q. 내부 팀용 API 문서도 공개 API 문서처럼 자세히 써야 하나요?

내부 팀용은 공개 문서보다 간략해도 됩니다. 그러나 최소한 엔드포인트 목록, 인증 방식, 주요 에러 코드는 작성해야 합니다. 문서 없는 내부 API는 팀 온보딩 시간을 크게 늘립니다.

마무리

이 글에서 정리한 기준을 실제 작업에 적용할 때는 [텍스터브 글자수 세기](/tools/char-counter/) 도구로 분량을 직접 확인하면서 진행하면 더 정확하게 맞출 수 있다.