[Spring/Backend] 프로젝트 개발 1주차. API 문서 작성하기

진행하기 전에 간단한 와이어프레임 제작과 기능 상세에 대해서는 마친 상태

개발 1주차부터 본격적으로 프론트엔드와 백엔드로 분리해서 파트 진행

 

백엔드는 ERD 설계까지 마친 상태로 1주차에는 API명세 작성과 회원가입/로그인 기능으로 나누어 진행

 

나는 API 명세 작성을 맡았다

 

프론트엔드와 본격적인 협업이 처음이고, 팀원들이 프로젝트 경험이 거의 없으므로 가능한 이해하기 쉽게 명세를 작성하기 위한 틀을 만들고자 했다

 

 

서칭을 해보며 여러 형태의 API 문서를 살펴보고 내가 원하는 방식으로 조합해서 만드는 것이 가장 적합할 것 같다고 판단하여 Notion을 사용해 직접 틀을 만들었다.

 

우선 주요 역할별 테이블을 만들고 그 안에서 세부 기능들을 쪼개어 작성하였다.

프론트엔드 팀원들이 궁금한 점이 생기면 물어볼 수 있도록 기능별 담당자와 진행도에 대해서도 표시해두었다.

 

테이블에서는 크게 API 이름, HTTP Method, URI, Return Page를 명시해두었다.

return page의 경우 프론트나 기획 단계에서 정하는 경우가 많다고 들었는데 우리 팀은 기획자가 따로 없기도 하고 다들 초보라서 그냥 내가 연습삼아 추가해보았다.

 

각 API에 대한 request와 response 또한 확인할 수 있도록 각 칼럼 내부에 디테일한 내용들을 담았다.

아래는 회원가입 POST API의 예시이다

 

Request

{
		"id":"groupin",
		"password":"groupin1234",
		"nickname":"송편",
		"email":"groupin@naver.com",
		"region":"서울",
}

정상처리

{
		"successful":true,
		"code":0,
		"msg":"회원가입에 성공하였습니다."
		"data":"eajiejaio01229jdk.dfajk01479dfajkljlkajklaqianvkl20na201d"
}

예외처리

• 이미 존재하는 아이디일 경우

{
		"successful":false,
		"code":-1,
		"msg":"회원가입에 실패하였습니다."
		"data":[
				{
						"field":"id",
						"defaultMessage":"이미 존재하는 아이디입니다.",
						"rejectedValue":"a"
				}
		]
}

• 이미 존재하는 닉네임일 경우

{
		"successful":false,
		"code":-1,
		"msg":"회원가입에 실패하였습니다."
		"data":[
				{
						"field":"nickname",
						"defaultMessage":"이미 존재하는 닉네임입니다.",
						"rejectedValue":"a"
				}
		]
}

• 이메일 형식이 아닐 경우

{
		"successful":false,
		"code":-1,
		"msg":"회원가입에 실패하였습니다."
		"data":[
				{
						"field":"password",
						"defaultMessage":"이메일 형식을 지켜주세요.",
						"rejectedValue":"aaa1naver.com"
				}
		]
}

• 비밀번호 형식에 어긋나는 경우

{
		"successful":false,
		"code":-1,
		"msg":"회원가입에 실패하였습니다."
		"data":[
				{
						"field":"email",
						"defaultMessage":"비밀번호는 8자리 이상 16자리 이내로 설정해주세요.",
						"rejectedValue":"aaa1"
				}
		]
}

 

하지만 이렇게 API를 모두 작성하려니 (개발 기간에 투자할 시간도 부족하여) 문서 작성 기간이 너무 빠듯하기도 하고 개발 중 계속 변동이 생기어 이부분은 일부 예시와 틀만 만들어두고 담당자별로 채워나가는 것으로 정하였다.

 

간단한 API 명세 정도는 해본 적 있지만 이렇게 구조까지 만들어고 본격적으로 작성해본 것은 처음이라 여러 레퍼런스를 찾아보고, 시도해보느라 시간이 오래 걸린 것 같다.

그래도 이번 경험을 기반으로 다음 프로젝트에서는 보다 빠르게 문서를 작성하고 활용할 수 있을 것 같아 뿌듯하다!