API 명세서 작성법, 항목과 예시 정리
API 명세서 작성법에서 어떤 항목부터 채워야 개발팀과 이야기가 통할까요? 요청·응답·인증과 에러 코드, 가상의 주문 조회 예시, 작성 도구 비교와 변경 이력 관리 방법을 정리합니다.
안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.
오늘의 인사이트 요약
API 명세서 작성법의 뼈대는 엔드포인트, HTTP 메서드, 요청, 응답, 에러 코드, 인증 여섯 칸입니다.
API 명세서 예시에는 성공 응답과 실패 응답이 함께 들어가야 쓸모가 생깁니다.
작성 툴은 노션, 스프레드시트, OpenAPI 기반 중 누가 읽고 누가 고치는지 보고 고릅니다.
API 명세서는 클라이언트와 서버가 어떤 요청과 응답을 주고받을지 정리한 문서입니다. 경로와 HTTP 메서드에 더해 값의 타입, 인증과 실패 응답까지 적어야 구현할 때 해석이 어긋나지 않습니다. 오늘은 API 명세서 작성법을 항목과 예시, 작성 도구와 관리 순서로 알아보겠습니다.
API 명세서 작성법, 어떤 항목부터 채울까
API 명세서 양식은 팀마다 모양이 달라도, 서버와 클라이언트의 약속을 적는 문서라 칸은 거의 같습니다.
첫 줄은 엔드포인트와 HTTP 메서드입니다.
일반적인 HTTP 의미에서 GET은 조회, POST는 생성이나 상태 변경, PUT은 전체 교체, PATCH는 일부 수정, DELETE는 삭제입니다.
요청 칸에는 파라미터마다 타입과 필수 여부를 적습니다.
경로 파라미터, 쿼리, 본문(body)을 나눠 두면 값마다 타입과 필수 여부를 붙이기 쉽습니다. 날짜처럼 헷갈리는 값에는 예시 값도 넣어 둡니다.
응답 칸은 성공과 실패를 같이 적습니다.
성공 응답만 있으면 화면을 만드는 쪽은 실패 상황을 짐작으로 채웁니다. 상태 코드별 본문과 에러 메시지 필드까지 들어가야 합니다.
인증은 API마다 한 칸을 따로 둡니다.
로그인이 필요한지, 토큰을 어느 헤더에 넣는지를 API 단위로 적어 둡니다.
API 명세서 예시, 주문 상세 조회 한 건으로 보기
가상의 쇼핑몰 앱의 주문 상세 조회 API로 양식을 채웠습니다.
항목 | 작성 예 |
|---|---|
엔드포인트·메서드 | GET /v1/orders/{orderId} |
요청 | 경로 파라미터 orderId (문자열, 필수) |
인증 | 필요, Authorization 헤더에 토큰 |
성공 응답 | 200, 주문 번호·상품 목록·결제 금액·배송 상태 |
에러 응답 | 401 로그인 필요, 403 다른 사람의 주문, 404 없는 주문 |
에러 코드는 화면 처리와 함께 읽힙니다.
401은 유효한 인증 자격이 없어 인증이 필요한 응답이고, 403은 서버가 요청을 이해했지만 이행을 거부하는 응답입니다. 인증된 사용자에게 권한이 부족한 상황이 403의 대표적인 예입니다. 주문의 존재 자체를 숨기려면 404로 응답하는 정책도 정할 수 있습니다. 명세서에 이 구분이 있으면 디자이너가 401은 로그인 화면으로, 403은 안내 문구로 보내는 흐름을 미리 그립니다.
정해진 값은 목록과 뜻을 모두 적습니다.
배송 상태가 READY, SHIPPING, DONE 중 하나로 온다면 세 값과 각각의 뜻을 빠짐없이 적습니다.
API 명세서 작성 툴, 노션·스프레드시트·OpenAPI 중 무엇을 고를까
API 명세서 작성 툴을 고를 때는 누가 읽고 누가 고치는지부터 따집니다.
노션은 기획과 디자인이 읽기 편합니다.
API마다 페이지를 만들어 데이터베이스로 묶으면 담당자와 진행 상태가 함께 붙지만, 서버 코드가 바뀌어도 문서는 저절로 따라오지 않습니다.
스프레드시트는 초기 목록을 뽑을 때 좋습니다.
응답 구조가 깊어지면 셀 하나에 담기 버겁지만, 한 행에 API 하나씩 넣으면 전체 개수와 빈칸이 한눈에 보입니다.
OpenAPI 기반 문서는 코드와 함께 움직입니다.
OpenAPI는 API 구조를 YAML이나 JSON으로 적는 표준 형식입니다. 이 파일을 Swagger UI 같은 도구에 넣으면 웹 문서로 펼쳐지고, 그 화면에서 요청도 직접 보내 볼 수 있습니다. 기획자가 바로 고치기는 어렵지만, API 명세를 서버 코드에서 생성하면 코드와 문서가 어긋날 일이 줄어듭니다.
기획·디자인·개발이 함께 보는 API 명세서 작성법
API 명세서 작성법에서 자주 놓치는 부분은 쓰고 난 뒤의 관리입니다.
원본은 한 곳에만 둡니다.
초기에는 노션으로 합의하고, 개발이 시작되면 OpenAPI 문서를 원본으로 삼는 식으로 시점마다 기준 문서를 정합니다.
API마다 쓰이는 화면을 적어 둡니다.
API 옆에 화면 이름을 적어 두면 디자인이 바뀌었을 때 영향받는 API가 바로 보입니다.
바뀐 내용은 날짜와 함께 남깁니다.
필드를 추가하거나 이름을 바꿨다면 변경 이력에 남기고 관련 직군에 알립니다. 외주라면 견적서의 범위 문서 옆에 명세서 초안을 붙여 두면 범위 논의가 구체적이 됩니다.
여섯 칸과 실패 응답을 채워 원본을 한 곳에 두면 기획자와 디자이너도 명세서를 펼쳐 봅니다. 프로젝트를 맡길 팀에게 던질 질문도 여기서 나옵니다. 이 API 명세서를 기획자와 디자이너도 같이 보나요? 답을 정해 두면 변경 내용을 함께 확인할 사람도 분명해집니다.
설정과 적용 조건을 더 살펴보려면 OpenAPI 명세 구조 · HTTP 상태 코드 의미를 참고해 보세요.
서비스 흐름과 API 설계를 함께 봅니다
똑똑한개발자는 기획·디자인·개발·운영을 함께하며 웹·앱과 관리자 시스템을 만듭니다. 화면이 필요한 데이터와 서버가 처리할 규칙을 같이 살피는 과정이 API 명세의 출발점입니다. 개발할 기능과 예외 상황을 연결해 문서에 담을 범위를 정리합니다.
화면은 있는데 API 목록을 어디부터 적을지 고민되시나요? 아래 링크로 문의해 주시면 화면별 요청과 응답, 인증 조건을 함께 살펴보겠습니다.
감사합니다. :)
API 명세서의 필수 항목과 주문 조회 예시를 살펴봅니다.
https://www.toktokhan.dev/contact?utm_source=landing&utm_campaign=api-specification-guide&utm_medium=api-specification-guide&utm_term=api-%EB%AA%85%EC%84%B8%EC%84%9C-%EC%9E%91%EC%84%B1%EB%B2%95