백엔드 담당으로 팀 프로젝트를 담당하다보면 api를 만들고 프론트한테 api에 대한 것들을 설명해야 할 경우가 많다. 항상 노션이라던가 구두로 이건 어떻게 저건 어떻고 등 설명을 해왔는데 시간도 오래걸리고 프론트단이 한번에 이해못하는 경우가 많았다. 이를 어떻게 해야하나 고민하던 도중 'API문서'라는 것을 알게되었고 적용한 내용을 작성해보고자 한다.
어떤 api는 body안에 어떤 데이터를 제공해야하고 헤더는 어떻고 queryString과 pathVariable은 어떤지, 더욱이 response때 데이터나 헤더는 어떤지 API 유형은 어떤지 등 프론트 단에서는 모든 정보가 다 궁금할 것이다. 정보를 확실히 알아야 적용을 할 수 있으니까 말이다. 그렇기에 백엔드 단에서는 정보들을 문서화에서 제공을 해주는데 그것이 API문서이다. 협업에 있어서 매우 중요한 과정으로 API 문서를 작성하는 방식은 다양하게 있다.
아래는 저번 프로젝트 진행중 작성한 예시 API문서이다.
https://documenter.getpostman.com/view/14960809/2s83YVH6Dk
culturemates
# Introduction What does your API do? # Overview Things that the developers should know about # Authentication What is the preferred way of using the API? # Error Codes What errors and status codes can a user expect? # Rate limit Is there a limit to the nu
documenter.getpostman.com
위와 같이 API문서를 url로 추출이 가능하고 단순하게 url을 들어가기만 하면 아래사진과 같이 필요한 정보들을 쉽게 확인할 수 있다.
그렇기에 프론트단에서는 위 문서만 가지고 어떤 api가 있고 요청시 어떤 입력이 있어야하고 응답시 각 기능 및 데이터들을 쉽게 확인할 수 있다.
작성하는 법은 간단하다. Postman 을 설치하고 백엔드 서버를 돌리고 http Method에 따라(get, post, put, delete) body와 header 및 queryString, pathVariable를 입력하여 api를 실행시키면 구현한 api에 따라 response가 출력되게 된다. 하나의 url을 뽑으면 postman 상에서 api들을 추가해도 뽑은 url에서 언제든지 최신의 업데이트 상태를 확인할 수 있다. 매우 편하지 않는가?
이제부터 API문서를 작성하는 방법에 대해 설명해 보겠다.
먼저 Postman에 들어간다. workspace가 없다면 workspace를 생성한다.
생성한 후 해당 workSpace로 들어가서 새로운 Collection을 생성한다. collection은 하나의 프로젝트 단위라고 생각하면 편하다.
생성한 후 add request를 통해 request를 작성할 수 있다.
클릭한 후 아래와 같이 Http Method 및 파라미터, body, header 등 필요한 정보들을 기입한 후 send를 누르면 response이 출력된다. 여기서 주의할 것은 url이 있는 서버가 실행되고 있어야 한다.
Send를 클릭하면 아래와 같이 응답이 나올 것이다.
그리고 아래 사진과 같이 파일모양을 클릭하면 Add request description 이라고 써져있는 곳에 자세한 설명을 작성할 수가 있다.
이후 Response가 나오는 화면에 우측에 Save Response를 클릭하여 Save as example를 클릭하여 예시를 저장한다.
이제 작성한 request들이 들어있는 collection을 문서로 만들어보자. 좌측에 My Workspace옆에 New 를 클릭하여 API Documentation을 클릭하자.
아래와 같이 나올텐데 미리 작성했던 collection을 클릭하여 다음으로 넘어간다.
그러면 아래와 같이 양식이 나올텐데 자유롭게 작성하자.
save를 누르면 아래와 같이 view documentation 이 나오는데 위 문서는 아직 workspace 내에서만 볼 수 있다.
다른 사람과 공유를 하고 싶으면 publish를 클릭한다.
클릭하면 페이지 설정을 할 수 있는 사이트로 넘어가고 아래로 넘기면 save and publish 버튼이 있다. 이를 클릭하면 완성된다. 그러면 아래와 같이 url이 나온다
위 url로 넘어가면 아래와 같이 완성된 페이지가 나온다.
위 페이지는 request를 추가할 때마다 자동으로 반영되서 프론트단에는 처음에 나오는 url하나만 넘기면된다.
이렇게 postman을 통한 api문서화를 알아보았다. 이외에도 postman에는 많은 기능이 있는데 우선 이 내용만 작성하고 이만 마치겠다.
참고
POSTMAN으로 API 문서화 짱 쉽게 하기
POSTMAN으로 문서화를 편하게 합시다🤭
velog.io
'프로젝트 관련' 카테고리의 다른 글
| springboot delete시 DB접근, 쿼리 횟수에 대한 고찰(mybatis, jpa) (0) | 2023.06.24 |
|---|---|
| sprigboot 프로젝트 진행중 리펙토링 적용 (0) | 2023.04.01 |
| AWS RDS를 통한 관계형 데이터베이스 구축 및 springboot 연동 (0) | 2023.02.22 |
| Jenkins를 활용한 React, Springboot CI,CD 구현(2) (0) | 2023.01.21 |
| Jenkins를 활용한 React, Springboot CI,CD 구현(1) (0) | 2023.01.18 |
