예외 처리에 대한 rest doc 작성하기
안녕하세요!
강사님 덕분에 테스트에 많은 관심이 생겨 개인 프로젝트에도 적용을 해보고 있습니다!
Rest doc 작성 중 궁금한 점이 생겨 질문드립니다.
API의 정상 응답이 아닌 예외 발생 시의 응답도 Rest doc으로 작성하고자 합니다.
예를 들어 인증, 인가 관련하여 예외가 발생하는 경우가 있을 때 다음과 같이 생각했습니다.
예외 케이스 별로 에러 코드를 상세하게 나누어 세밀한 응답을 전달하기 (ex. 아이디가 틀렸을 때 - 401A, 비밀번호가 틀렸을 때 - 401B, 아이디가 존재하지 않을 때 - 401C 등등..)
공통 예외코드로 처리하기 (ex. 인증 실패 시 어떤 경우라도 401 코드 반환)
위의 2가지 경우에 어떤 식으로 rest doc을 작성하는 것이 좋을까요? 1번 케이스의 경우는 특정 API 문서마다 함께 적는 것이 좋을 것 같긴 한데 2번 케이스의 경우는 프로젝트 전반적인 공통 예외처리라 별도의 문서 항목으로 1개만 작성하는 게 좋을 지 고민이 됩니다.
혹시 현업에서는 예외 발생 시 응답에 대한 문서도 작성하시는 지 궁금하고
1번, 2번 케이스에 대하여 어떻게 rest doc을 작성하는 것이 다른 인원과 소통하기 편할지 의견 부탁드리겠습니다!
감사합니다.
답변 2
2
안녕하세요, 원준님! :)
질문 주신 글에 제가 드릴 답도 있는 것 같아요 ㅎㅎ
말씀 주신대로 1번 케이스일 때에는 해당 예외사항이 발생할 수 있는 API 문서에 같이 적으면 좋을 것 같고, 2번 케이스일 때는 별도 섹션을 만들어서 안내하면 좋지 않을까 합니다.
실무에서는 저 같은 경우, 필요하다고 판단하면 작성하고 있고요.
보통은 일반적인 명세만으로 충분하기도 해서 해당 문서와 관련된 이해관계자 분들과 충분한 소통 후에 결정하고 있습니다.
도움이 되셨기를 바랍니다.
감사합니다. :)
1
안녕하세요, 인프런 AI 인턴이에요.
REST API의 예외 처리에 대한 응답 문서를 작성하는 방법에 대해 궁금하신 거죠? 예외 상황에 대한 응답을 문서로 작성하는 것은 좋은 방법입니다. 이를 통해 프로젝트에 참여하는 다른 인원들과 원활한 소통을 할 수 있을 거예요.
1번 케이스의 경우, 특정 API 문서마다 예외 상황에 대한 응답을 함께 작성하는 것이 좋은 방법입니다. 예를 들어, 아이디나 비밀번호가 틀렸을 때와 아이디가 존재하지 않을 때에 대한 예외 상황에 대한 응답을 해당 API의 문서에 자세히 작성해주시면 됩니다. 이렇게 함으로써 개별 API에 대한 응답 문서가 구체적이고 자세해져, 협업하는 다른 개발자들이 이해하기 쉬워집니다.
2번 케이스의 경우, 공통 예외 상황에 대한 처리를 문서의 별도 항목으로 작성하는 것도 좋은 방법입니다. 예를 들어, 인증 실패에 대한 응답을의 경우, 모든 인증 실패 상황에 대해 공통으로 동일한 401 코드를 반환하는 것이 좋다면, 이를 별도로 작성하여 프로젝트의 전반적인 예외 처리 항목에 기술해주시면 됩니다.
현업에서도 예외 발생 시 응답에 대한 문서를 작성하는 경우가 많이 있습니다. REST API의 예외 상황에 대한 응답 문서를 작성하여 다른 개발자들과의 소통을 원할하게 할 수 있습니다.
어떤 방식을 선택하더라도, 문서 가독성을 높이고 읽기 쉽게 작성하는 것이 중요합니다. 각각의 상황에 대한 응답을 명확하고 간결하게 작성하여 다른 개발자들이 이해하기 쉽도록 해야 합니다.
혹시 추가적인 도움이 필요하시다면, 더 자세한 내용이나 예시가 있다면 알려주세요. 도움을 드릴 수 있도록 최선을 다하겠습니다. 감사합니다.
private 상수 테스트 관련 질문
0
83
1
void는 어떻게 테스트하나요..? void로 애초에 코딩하면 안되나요??
0
126
2
커버리지는 어떻게 활용하시는지 궁금합니다.
0
161
2
테스트 문서화 질문입니다
0
105
2
단위테스트 질문이 있습니다
0
96
2
컨트롤러는 모킹을 한 이유가 궁금합니다.
0
103
2
ERD 가장자리에 있는 도메인 테스트 질문
0
89
2
DTO 검증 필드에 대한 테스트 코드 작성은 어디까지?
0
135
2
OrderCreateRequest DTO에 대해서 궁금한점
0
102
2
고전파의 테스트 대역 사용 대상, 공유 의존성
0
156
2
계층 관련 질문이 있습니다.
0
139
3
'코틀린'에서는 빌더를 따로 쓰지 않는데, 이 때는 어떻게 test fixture를 만드시는지 궁금합니다
1
124
2
혹시 update 로직은 어떻게 테스트하나요? (@Setter?)
0
135
2
단위테스트와 통합테스트의 경계가 궁금합니다.
0
228
2
Service+Repository 통합테스트 관련 질문입니다.
0
150
2
OrderControllerDocsTest 작성 해봤는데요. 날짜 형식이 이상하게 나와요
0
185
2
test 용 .yml
0
90
2
throws Exception
0
80
2
카페키오스크 클래스 문의 ,,
0
89
2
Rest docs 문서용 테스트코드를 따로 작성해야 되나요?
0
174
2
테스트 코드에서 필요한 생성자
0
138
1
tearDown 순서
0
116
2
@Builder 생성자 private
0
136
2
@DisplayName gradle / intellJ
0
93
2