API 문서는 무엇을 보내고, 어떤 결과를 받는지를 설명하면 됩니다.
1. 필수 항목은 여섯 가지
| 항목 | 적을 내용 | 예시 |
|---|---|---|
| 목적 | 누가 무엇을 하는가 | 본인 주문 상태 조회 |
| 메서드·URL | 호출 방법과 경로 | GET /v1/orders/{orderId} |
| 인증 | 인증 방식과 권한 | Bearer 토큰, 주문 소유자 |
| 요청 | 입력 위치·타입·필수 여부 | 경로의 orderId, 필수 문자열 |
| 성공 응답 | 상태 코드·필드·단위 | 200, 주문 상태·금액 |
| 오류 응답 | 실패 조건과 처리 방법 | 404이면 주문 ID 확인 |
입력 값에는 허용 범위와 예시를, 응답 필드에는 항상 포함되는지와 null 허용 여부를 덧붙이세요.
2. 주문 조회 예시로 보기
아래 주소와 데이터는 설명용입니다. 실제 서버가 아니며, 인증 값도 자리표시자입니다.
요청
GET https://example.invalid/v1/orders/ORD-20261102-001
Authorization: Bearer <ACCESS_TOKEN>
성공 응답 · 200 OK
{
"orderId": "ORD-20261102-001",
"status": "PAID",
"totalAmount": 39000,
"currency": "KRW",
"orderedAt": "2026-11-02T09:00:00+09:00"
}
이 예시에서 totalAmount는 원 단위 정수입니다. 날짜에는 시간대를 포함하고, status의 허용 값은 명세에 별도로 정의합니다.
실패했을 때
| 상태 | 오류 코드 | 호출자가 할 일 |
|---|---|---|
| 401 | UNAUTHORIZED | 로그인·토큰 갱신 |
| 404 | ORDER_NOT_FOUND | 주문 ID 확인 |
오류는 코드만 나열하지 말고 해결 방법을 적으세요. 상태 코드와 권한 처리는 실제 서버의 정책에 맞춥니다.
3. 양식을 내려받아 바로 작성하기
빈 문서 대신 아래 양식에 팀의 API 정보를 채워 보세요. OpenAPI 파일에는 위 조회 API와 POST 주문 생성 예시가 함께 들어 있습니다.
주문 조회·생성 예제 · OpenAPI JSON 내려받기
OpenAPI 예제의 서버 주소도 가상 주소입니다. 실제 서버를 연결하려면 주소·인증·요청·응답을 구현에 맞게 수정하세요.
4. 전달 전, 세 가지만 확인하세요
- 동작 일치: 문서의 요청·응답·오류가 실제 테스트 결과와 같은가?
- 공유 범위: 실제 토큰·고객 정보 없이 상대에게 필요한 API만 담았는가?
- 전달 버전: 수정 중인 내용과 검토가 끝난 외부 제공본을 구분했는가?
도구 선택이 고민이라면 API 툴 비교 글을, 명세 형식의 세부 기준은 OpenAPI 3.0.3 공식 명세를 참고하세요.
이 글은 API 문서 작성·검토·공유 도구를 만드는 스펙브릿지 팀이 작성했습니다.