API 문서 양식

백엔드에서 작업한 API를 사용하기 위한 기본 정보를 프론트엔드에 API 문서로 전달하는 것이 여러 모로 보기 좋고 의사소통에도 도움이 된다.

 

• API 문서 작성 이유

API 문서화 도구인 Swagger를 사용하기도 하지만, Swagger만으로는 전달하는 정보에 한계가 있다.

예를 들면, ENUM 값을 어떤 것들을 넣을 수 있는지, Response body에서 어떤 값들이 필수인지 아닌지 등이다.

 

• API 문서 작성 위치

보통은 팀에서 사용하는 업무용 위키에 올려 공유하면 편하다. 현재 팀에서는 Confluence를 사용 중이다.

 

 

그래서 업무를 하면서 사용하기 좋았던 API 문서 양식을 글로 작성해 보았다.

 

*혹시 더 좋은 양식이 있다면 댓글로 의견 주세요!!

 

(API 이름) GetADetail

---

Request URL

Method	URL	인증 방식
GET	/A/{AId}	accessToken

 

 

Path Parameter

Name	Type	Description	Required
AId	Long	A의 ID	O

 

 

Headers

Authorization: Bearer ${accessToken}

Name	Type	Description	Required
Authorization	String	사용자 인증 수단, 엑세스 토큰 값	O

 

Request body

Request body가 있을 경우 입력
json 양식 등

 

Name	Type	Description	Required
userId	String	유저 id	O
...	...	...	...

 

Response body

Response body가 있을 경우 입력
json 양식 등

 

Name	Type	Description	Required
id	Long	id	O
Title	String	타이틀명	O
placeCoordinate	List<String>	주소의 위도, 경도	O
...	...	...	...

 

 

Error code

Code	Type	Description
ME0004	NOT_FOUND	Not found email auth info.
...	...	...