[REST API] API 문서 작성

API 문서 작성

API 문서란?

API 문서는 개발자와 사용자가 원활하게 API를 파악하고 사용할 수 있도록 돕는 문서다.

API의 기능,  데이터 형석, 사용 방법, 오류와 같이 API를 사용하기 위해서 알아야하는 제약들을 명시한다.

좋은 내부 API에 문서는 개발이 원활히 진행될 수 있도록 도와준다.

 

고려해야 하는 사항

1. 출력 형식이 바뀌어도 쉽게 적응할 수 있어야 한다.

2. 작성하는 사람이 뭘 써야 하는지 쉽게 알 수 있어야 한다.

 

작성 방법

개발 시작 전 각 API의 기능, 이를 위해 사전에 필요한 사항, 주고받을 데이터 등이 포함된 API 문서 초안을 작성한다. 이를 통해 API 개발의 방향을 명확히 할 수 있으며, 문서 초안 공유 후 피드백을 받을 수도 있다.

 

포함되어야 하는 항목

 

개요 (Overview):

API가 무엇인지, 어떤 기능을 제공하는지, API 호출 방법 등을 설명합니다.

 

인증 (Authentication):

API 호출에 필요한 인증 방법과 키 발급 방법 등을 설명합니다.

 

요청 (Requests):

API 호출에 필요한 요청 형식, 파라미터, 헤더 등을 설명합니다.

 

응답 (Responses):

API 응답에 대한 형식과 응답 코드, 오류 처리 등을 설명합니다.

 

예제 (Examples):

API 사용 예제를 제공합니다.

 

엔드포인트 (Endpoints):

API 엔드포인트 URL 및 버전 정보를 제공합니다.

 

리소스 (Resources):

API가 제공하는 리소스(데이터)에 대한 설명을 제공합니다.

 

한계 (Limits):

API 호출 제한, 쿼터(Quota) 등에 대한 설명을 제공합니다.

 

참고자료 (References):

API 관련된 참고 자료 및 링크를 제공합니다.

 

 

API  문서 제작 툴 추천

Postman (https://www.postman.com/)

• API 요청을 직접 날려볼 수 있다.
• API 사용 예제 저장이 가능하다.
• 테스트 케이스 작성이 가능하다.

Gitbook (https://www.gitbook.com/)

• 데이터, 응답 등을 한눈에 확인 할 수 있는 UI로 가독성이 좋다.

 

<참고>

- https://tech.kakaoenterprise.com/127

- https://www.writethedocs.org/guide/