본문으로 이동
API 문서 작성

API 작성 방법: 예시로 보는 명세서 양식

API 문서 필수 항목과 주문 조회 예시를 한눈에. Markdown 양식과 OpenAPI 예제를 바로 받아보세요.

목차 보기

API 문서는 이 순서로 정리하세요

  • 요청

    주소·인증·보낼 값

  • 응답

    성공 결과·오류 처리

  • 검토·공유

    실제 동작 확인·전달

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의 허용 값은 명세에 별도로 정의합니다.

실패했을 때

상태오류 코드호출자가 할 일
401UNAUTHORIZED로그인·토큰 갱신
404ORDER_NOT_FOUND주문 ID 확인

오류는 코드만 나열하지 말고 해결 방법을 적으세요. 상태 코드와 권한 처리는 실제 서버의 정책에 맞춥니다.

3. 양식을 내려받아 바로 작성하기

빈 문서 대신 아래 양식에 팀의 API 정보를 채워 보세요. OpenAPI 파일에는 위 조회 API와 POST 주문 생성 예시가 함께 들어 있습니다.

API 명세서 양식 · Markdown 내려받기

주문 조회·생성 예제 · OpenAPI JSON 내려받기

OpenAPI 예제의 서버 주소도 가상 주소입니다. 실제 서버를 연결하려면 주소·인증·요청·응답을 구현에 맞게 수정하세요.

4. 전달 전, 세 가지만 확인하세요

  • 동작 일치: 문서의 요청·응답·오류가 실제 테스트 결과와 같은가?
  • 공유 범위: 실제 토큰·고객 정보 없이 상대에게 필요한 API만 담았는가?
  • 전달 버전: 수정 중인 내용과 검토가 끝난 외부 제공본을 구분했는가?

도구 선택이 고민이라면 API 툴 비교 글을, 명세 형식의 세부 기준은 OpenAPI 3.0.3 공식 명세를 참고하세요.

이 글은 API 문서 작성·검토·공유 도구를 만드는 스펙브릿지 팀이 작성했습니다.

← 모든 글 보기