API 작성을 위해 문서·명세서를 정리할 때는 목적 → 메서드·URL → 인증 → 요청 → 성공 응답 → 오류 → 변경·공유 기준 순서로 작성하면 됩니다. 다른 개발자가 문서만 보고 요청을 만들고 결과를 처리할 수 있는지가 기준입니다.
이 글은 API 문서 작성 방법을 찾는 개발자를 위해 가상의 주문 조회·생성 API를 예로 듭니다. 실제 서버 구현과 문서 내용을 대조하는 검토까지 다룹니다. 예시는 설명용이며 실제 고객 데이터나 운영 API가 아닙니다.
API 작성 방법을 한눈에 보는 순서
| 순서 | 작성할 내용 | 주문 API 예시 |
|---|---|---|
| 1 | 목적과 사용 범위 | 로그인한 사용자가 본인 주문을 조회 |
| 2 | HTTP 메서드와 경로 | GET /v1/orders/{orderId} |
| 3 | 인증과 권한 | Bearer 토큰, 주문 소유자 확인 |
| 4 | 요청 값과 제약 | orderId는 필수 문자열 |
| 5 | 성공 응답과 필드 | 200, 주문 상태·금액·통화 |
| 6 | 오류와 처리 방법 | 401은 인증 확인, 404는 주문 ID 확인 |
| 7 | 검토와 외부 제공 기준 | 실제 응답과 대조한 뒤 전달할 버전 선택 |
한 기능의 정상 요청을 먼저 적고, 잘못된 입력과 권한 없는 요청을 추가해 보세요. 문서 제목만 바꾸거나 필드 이름만 나열하기보다 호출자가 각 상황에서 다음 행동을 판단할 수 있게 설명하는 것이 좋습니다.
API 문서·명세서 작성에 필요한 필수 항목
문서 양식을 정할 때는 다음 질문에 답할 수 있는지 확인하세요.
- 어떤 일을 하는 API인가? 이름, 목적, 메서드, 경로를 적습니다.
- 어디로 요청하는가? 개발·운영 환경의 기본 주소를 구분합니다.
- 누가 호출할 수 있는가? 인증 방식과 필요한 권한을 설명합니다.
- 무엇을 보내는가? 경로 변수, 쿼리, 헤더, 본문을 나눠 적습니다.
- 어떤 결과를 받는가? 상태 코드와 응답 필드, 예시를 제공합니다.
- 실패하면 어떻게 처리하는가? 오류 코드와 재시도·수정 방법을 설명합니다.
OpenAPI를 사용하는 경우 매개변수는 parameters, 요청 본문은 requestBody, 응답은 responses로 구분합니다. 형식을 정하는 것과 실제 서버 동작을 검증하는 것은 별도 작업입니다.
예시 1. 목적과 호출 주소
API 이름: 주문 단건 조회
목적: 로그인한 사용자가 본인 주문의 처리 상태와 결제 금액을 조회합니다.
메서드·경로: GET /v1/orders/{orderId}
예시 기본 주소: https://api.example.com
단순히 “주문 조회”라고만 쓰면 조회 가능한 범위가 불명확합니다. 본인 주문만 조회할 수 있다는 조건처럼 권한에 영향을 주는 제약도 함께 적으세요. 예시 주소는 실제로 호출하는 주소가 아닙니다.
예시 2. 인증과 요청 값
이 예시 API는 Authorization 헤더의 Bearer 토큰으로 인증합니다. 문서에 실제 토큰을 넣지 말고 자리표시자를 사용하세요.
| 위치 | 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| 헤더 | Authorization | string | 예 | Bearer <ACCESS_TOKEN> |
| 경로 | orderId | string | 예 | 조회할 주문 ID. 예: ORD-20261102-001 |
GET 요청의 이 예시에서는 요청 본문을 사용하지 않습니다. POST 등에서 본문을 받는다면 본문 형식과 각 필드의 타입, 필수 여부, 허용 값, 길이 제한도 적으세요. “값 없음”, null, 빈 문자열을 어떻게 처리하는지도 연동 시 확인할 항목입니다.
예시 3. 성공 응답과 필드 설명
성공 상태 코드: 200 OK
숫자 필드는 단위를 적어야 오해를 줄일 수 있습니다. 여기서 totalAmount는 원 단위 정수이며, status는 예시에 정의한 문자열만 반환한다고 가정합니다.
{
"orderId": "ORD-20261102-001",
"status": "PAID",
"totalAmount": 39000,
"currency": "KRW",
"orderedAt": "2026-11-02T09:00:00+09:00"
}| 필드 | 타입 | 설명 |
|---|---|---|
| orderId | string | 주문 ID |
| status | string | CREATED, PAID, PREPARING, SHIPPED, CANCELLED 중 하나 |
| totalAmount | integer | 결제 총액. 원 단위 |
| currency | string | 이 예시에서는 KRW |
| orderedAt | string | UTC 오프셋을 포함한 ISO 8601 형식의 주문 일시 |
실제 명세에는 필드가 항상 존재하는지, null을 반환할 수 있는지도 추가하세요. 페이지 목록 API라면 빈 목록, 마지막 페이지, 정렬 기준의 예시도 필요합니다.
예시 4. 오류 응답과 호출자의 다음 행동
오류 명세에는 메시지뿐 아니라 호출자가 무엇을 바꿔야 하는지 적는 것이 좋습니다. 아래 상태 코드는 이 가상 API가 선택한 동작이며, 모든 API가 같은 정책을 쓰는 것은 아닙니다.
| HTTP 상태 | 오류 코드 | 발생 조건 | 처리 방법 |
|---|---|---|---|
| 400 | INVALID_ORDER_ID | 주문 ID 형식이 맞지 않음 | 입력 형식 확인 |
| 401 | UNAUTHORIZED | 인증 토큰 누락·만료 | 로그인 또는 토큰 갱신 |
| 403 | FORBIDDEN | 해당 주문의 조회 권한 없음 | 권한·주문 소유자 확인 |
| 404 | ORDER_NOT_FOUND | 주문이 존재하지 않음 | 주문 ID 확인 |
{
"code": "ORDER_NOT_FOUND",
"message": "주문을 찾을 수 없습니다."
}보안 정책에 따라 권한이 없는 리소스의 존재를 숨기기 위해 404를 반환하는 설계도 가능합니다. 실제 제품의 정책과 구현에 맞게 문서화하세요. 호출 제한이 있다면 429 응답과 재시도 기준도 별도로 설명합니다.
POST API 작성 예시: 요청 본문과 생성 응답
조회 API와 생성 API는 요청·응답을 각각 설명해야 합니다. 같은 주문을 다루더라도 GET의 경로 변수와 POST의 JSON 본문은 입력 위치가 다릅니다.
메서드·경로: POST /v1/orders
인증: Authorization: Bearer <ACCESS_TOKEN>
본문 형식: Content-Type: application/json
{
"productId": "SKU-1001",
"quantity": 2
}| 필드 | 타입 | 필수 | 제약 |
|---|---|---|---|
| productId | string | 예 | 주문할 상품 ID |
| quantity | integer | 예 | 1 이상 100 이하 |
가격은 서버가 상품 정보를 기준으로 계산하는 예시입니다. 여기서는 수량 2개에 대한 총액이 38,000원이라고 가정합니다. 이 가상 API의 신규 주문은 CREATED 상태이며, 결제 처리는 예시에 포함하지 않습니다.
성공 상태 코드: 201 Created
생성한 리소스 위치: Location: /v1/orders/ORD-20261102-002
{
"orderId": "ORD-20261102-002",
"status": "CREATED",
"totalAmount": 38000,
"currency": "KRW",
"orderedAt": "2026-11-02T09:10:00+09:00"
}수량이 0이거나 필수 값이 없다면 이 예시에서는 400과 INVALID_REQUEST 오류를 반환합니다. 어떤 값이 잘못되었는지 호출자가 고칠 수 있도록 메시지를 작성하세요. 실제 서버가 다른 상태 코드나 오류 형식을 쓴다면 구현된 동작에 맞춰 명세도 바꿔야 합니다.
복사해서 쓰는 API 명세서 양식
아래 내용을 팀 문서에 복사한 뒤 빈 항목을 채우면 됩니다. 모든 API에 같은 항목이 필요한 것은 아니므로 실제 동작에 맞춰 조정하세요.
같은 주문 API의 OpenAPI 예제 내려받기 · JSON
OpenAPI 파일에는 위 GET·POST 경로와 요청·응답 구조를 함께 담았습니다. 서버 주소는 호출할 수 없는 예시 주소이며, 실제 서비스에 연결하려면 개발자가 승인한 주소·인증·실제 응답에 맞게 수정해야 합니다.
API 이름 / 목적:
담당자 / 최종 확인일:
개발·운영 기본 주소:
HTTP 메서드 / 경로:
인증 방식 / 필요한 권한:
요청 헤더:
경로·쿼리 파라미터 (이름, 타입, 필수, 제약, 예시):
요청 본문 (형식, 필드, 필수, null 허용, 예시):
성공 응답 (상태 코드, 필드, 단위, 예시):
오류 응답 (상태 코드, 오류 코드, 발생 조건, 처리 방법):
호출 제한 / 재시도 / 중복 요청 처리:
변경 내용 / 적용 예정일 / 외부 제공 버전:거래처에 전달하기 전 확인할 것
- 문서의 메서드·경로와 실제 테스트 결과가 일치하는가?
- 실제 고객 정보, 인증 토큰, 내부 전용 주소가 예시에 남아 있지 않은가?
- 실패 응답과 권한 조건도 설명했는가?
- 상대방에게 필요한 문서만 포함했는가?
- 작성 중인 초안과 외부에 제공할 버전을 구분했는가?
- 변경이 생겼을 때 담당자와 전달 대상을 확인할 수 있는가?
양식을 잘 만들어도 실제 API가 바뀌면 내용이 오래될 수 있습니다. 변경 내용을 검토하고 외부 배포본을 갱신하는 책임과 순서를 팀에서 정하세요. 이미 내려받은 파일은 공유 링크의 문서가 바뀌어도 자동으로 갱신되지 않습니다.
API 문서 작성에서 자주 묻는 질문
API 작성과 API 명세서 작성은 같은 뜻인가요?
API 작성은 서버 기능 구현까지 포함하는 표현으로 쓰이기도 합니다. 이 글에서 다루는 작업은 연동 개발자가 참고할 API 문서·명세서를 작성하는 일입니다. 구현한 서버의 요청·응답과 일치하는 문서를 만드는 것이 목적입니다.
API 명세서 양식을 엑셀이나 Markdown으로 작성해도 되나요?
가능합니다. 사용하는 형식에 관계없이 입력 위치, 타입, 필수 여부, 제약, 응답 예시, 오류를 확인할 수 있어야 합니다. 변경이 잦고 전달 대상이 많다면 최신본과 배포본, 변경 이력과 공유 범위를 어떻게 관리할지도 정하세요.
Swagger·OpenAPI 파일이 있으면 설명 문서를 또 만들어야 하나요?
기존 명세에 목적, 인증·권한 조건, 필드 제약과 예시가 충분하다면 그 명세를 관리하며 활용할 수 있습니다. 업무 규칙이나 오류 복구 방법처럼 추가 설명이 필요한 내용은 독자가 찾기 쉬운 곳에 보완하세요. 같은 정보를 여러 곳에 복제할 때는 변경을 함께 반영할 기준이 필요합니다.
API 문서 작성 도구는 어떤 기준으로 고르면 되나요?
요청·응답 구조를 정리할 수 있는지, 변경을 비교·검토할 수 있는지, 내부 수정본과 외부 제공본을 구분할 수 있는지 살펴보세요. 팀원과 거래처가 실제로 문서를 확인하는 과정까지 예시 데이터로 체험하는 것이 좋습니다.
스펙브릿지에서 작성·검토·공유 이어가기
스펙브릿지는 요청·응답 항목을 정리하고, 문서 변경 검토와 외부 배포·공유로 연결하는 도구입니다. 이 글은 제품을 만드는 스펙브릿지 팀이 작성했습니다.
명세 형식의 세부 기준은 OpenAPI 3.0.3 공식 명세를 참고하세요.