API 명세서 작성하기

1️⃣ API 명세서란?

백엔드 개발자가 설계한 API의 호출과 응답 관련 정보를 정리해 프론트 개발자에게 전달하는 문서입니다. 해당 문서를 바탕으로 프론트 개발자는 API의 사용 방법을 파악하고, 호출과 응답을 테스트하며, 서비스를 구현합니다.

 

---

 

2️⃣ API 명세서를 쓰는 이유?

백엔드는 API 문서가 있어야 기능을 정의하고 작업할 수 있고, 프론트엔드는 이를 바탕으로 백엔드에서 어떤 값이 올 지 알고 작업할 수 있습니다. 한 마디로 표준화된 API 명세서는 개발자 간의 협업을 촉진하고, 외부 개발자가 소프트웨어를 쉽게 이해하고 활용할 수 있게 합니다.

 

---

 

3️⃣ API 명세서 작성 도구

OpenAPI (Swagger), Postman, GitBook 등이 있습니다.

이러한 도구들은 가독성 높은 형식으로 API를 문서화하고, 자동화된 테스트를 제공하여 개발자의 작업 부담을 줄여줍니다.

 

✔ Swagger

무료로 제공되며, 문서 자체에서 바로 해당 API를 테스트 해볼 수 있습니다.

그러나 API를 카텍리 별로 나누는 기능이 없습니다.

 

✔  Postman

마크다운 형식으로 간단하게 문서 작성이 가능하고 UI가 깔끔합니다.

자동으로 문서 부분을 생성해주고, 사용 예시까지 알려주기 때문에, 해당 API에 대한 코멘트만 추가해주면 알아서 자동으로 API 문서를 만들어줍니다.

 

✔  GitBook

UI가 깔끔합니다. API를 테스트 해보는 기능은 없습니다.

 

 

---

 

4️⃣ 프로젝트 기록

일단 저는 누군가와 협업하는 팀프로젝트가 아니기 때문에 Notion을 활용해 제가 보기에 가장 편하게 수정하여 문서화 했습니다.

추후 위에 적어놓은 툴도 사용하여 작성하는 경험을 갖을 생각입니다!

 

양식은 차례대로 API카테고리 / 진행상태 / 기능 / 메소드 / REST API / 권한 / Request / Response 라고 구분했습니다.

 

✔ 메서드와 URI

REST API 형식을 채택했기 때문에 메소드와 Mapping이 될 URI를 정의했습니다.

• GET : 노출돼도 되는 정보 / 멱등하게 값을 보내줘야 할 때 / 단순 조회
• POST : body에 값을 넣어 보내줘야 할 때 / 로그인 등
• PUT : 특정 값을 수정할 때
• DELETE : 특정 값을 삭제할 때