Postman의 'API Documentation' 기능으로 API 문서화 가능
현재 프로젝트
- 현재 프로젝트에서는 팀 Notion의 API 문서 상에 표로 정리해두었다.
회원가입
로그인
로그아웃
토큰 재발급
회원정보 조회
회원정보 수정
회원 탈퇴
HTTP Status 설정
- 공통
-
성공 :
201 Created(200 OK와 달리, 공통 성공 응답에 대해 커스텀했기 때문에 구분을 위함)-
모두 동일하기 때문에 실패 status만 작성
-
기능별로 URI가 나누어져 있기 때문에 별도의 설명은 하지 않았으며, 해당 URI에서 성공했는지 여부만 검토하도록 구성했습니다.
ex) 데이터 O
{ "result": "success", "data": { ... } }데이터 X
{ "result": "success", "data": null }
-
-
실패 : `400 Bad Request` + 1(서버 번호) + 커스텀 오류 번호
ex) 4001000: 이미 가입되어 있는 이메일입니다.
-
4001까지는 동일 → 아래 3자리만 작성하겠습니다.
-
000 (
RuntimeException) -
회원가입 : 이미 가입되어 있는 이메일입니다.
-
토큰 재발급
- Refresh Token이 유효하지 않습니다.
- 로그아웃된 사용자입니다.
- 토큰의 유저 정보가 일치하지 않습니다.
-
정보 조회 : 로그인 유저 정보가 없습니다.
-
정보 수정 : 로그인 유저 정보가 없습니다.
-
로그아웃 : 로그인 유저 정보가 없습니다.
-
회원탈퇴 : 로그인 유저 정보가 없습니다.
❓왜 000인지❓
초기 개발 시에 공통 응답 코드에 대한 이야기가 나오기 전에 구현한 부분이었기 때문에 그대로 두었습니다.
응답 코드가 많아질 수록 코드의 양이 길어지고, 스프링과 인증 인가 서버의 구현이 처음인 저에게는 최소한의 경우의 수를 고려하여 관리가 가능한 수준으로 구현하기 위해 나누었던 경우의 수입니다!
응답 코드 개수를 늘리지 않고, 똑같이 runtimeException안에서 일어나는 간단한 문제 상황을 고려했습니다. 그렇기 때문에 아래의 1번대 응답 코드와 다소 겹치는 설명이 있을 수 있습니다.
응답 코드의 개수를 늘리지 않고, 어떤 오류인지 message에 담는 것이 조금 더 좋을 것이라 판단하여 그대로 남겨두었습니다.
-
101 (
BindException) -
EXIST_USER : 이미 존재하는 사용자입니다.
-
102 (
InternalAuthenticationServiceException) -
NO_SUCH_USER : 해당하는 사용자가 없습니다.
-
103 (
IllegalArgumentException) -
NO_MATCH_PASSWARD : 비밀번호가 일치하지 않습니다.
현재의 문제점
-
실패 응답 코드
-
다양한 응답에 대한 케이스를 작성함
→ 실제로 반영은 안되고 있음..
→ 그 이유? 응답에 대한 작성을 거의 해보지 않아, 자바에서 제공하는 툴 이상을 뛰어넘지 못해 실질적으로는 요청 시 맞춰야 할 조건에 부합하지 않으면 일반적인 Bad request로 귀결이 되고 있음.
→ 변경해보려 했으나
- 000 코드에 해당되는 부분을 작성하지 않고 1번대 코드를 작성하게 되면 알 수 없는 오류가 로그에 남게 되는데, 해결 방법이 없는 상태.
- 둘 다 작성을 하면, 기본 응답으로 돌아가 1번대 코드는 작성을 해도 반영이 안되는 상태.
-
인증/인가 서버의 응답 자체는 케이스가 거의 정형화 되어 있고, 현재로서는 코드는 아니더라도 message 상에 어떤 오류인지 명시하고 있기 때문에 문제는 없음.
→ 시간 여유가 생긴다면(…?) 해당 부분도 수정해보고 싶음.
-
추후 Postman을 활용하여 API 문서화를 해볼 예정.
