백엔드에서 작업한 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. |
| ... | ... | ... |