인프런 커뮤니티 질문&답변
작성한 질문수
예외 처리에 대한 rest doc 작성하기
해결된 질문
23.08.16 20:34 작성
·
389
0
안녕하세요!
강사님 덕분에 테스트에 많은 관심이 생겨 개인 프로젝트에도 적용을 해보고 있습니다!
Rest doc 작성 중 궁금한 점이 생겨 질문드립니다.
API의 정상 응답이 아닌 예외 발생 시의 응답도 Rest doc으로 작성하고자 합니다.
예를 들어 인증, 인가 관련하여 예외가 발생하는 경우가 있을 때 다음과 같이 생각했습니다.
예외 케이스 별로 에러 코드를 상세하게 나누어 세밀한 응답을 전달하기 (ex. 아이디가 틀렸을 때 - 401A, 비밀번호가 틀렸을 때 - 401B, 아이디가 존재하지 않을 때 - 401C 등등..)
공통 예외코드로 처리하기 (ex. 인증 실패 시 어떤 경우라도 401 코드 반환)
위의 2가지 경우에 어떤 식으로 rest doc을 작성하는 것이 좋을까요? 1번 케이스의 경우는 특정 API 문서마다 함께 적는 것이 좋을 것 같긴 한데 2번 케이스의 경우는 프로젝트 전반적인 공통 예외처리라 별도의 문서 항목으로 1개만 작성하는 게 좋을 지 고민이 됩니다.
혹시 현업에서는 예외 발생 시 응답에 대한 문서도 작성하시는 지 궁금하고
1번, 2번 케이스에 대하여 어떻게 rest doc을 작성하는 것이 다른 인원과 소통하기 편할지 의견 부탁드리겠습니다!
감사합니다.
답변 2
2
2023. 08. 20. 17:20
안녕하세요, 원준님! :)
질문 주신 글에 제가 드릴 답도 있는 것 같아요 ㅎㅎ
말씀 주신대로 1번 케이스일 때에는 해당 예외사항이 발생할 수 있는 API 문서에 같이 적으면 좋을 것 같고, 2번 케이스일 때는 별도 섹션을 만들어서 안내하면 좋지 않을까 합니다.
실무에서는 저 같은 경우, 필요하다고 판단하면 작성하고 있고요.
보통은 일반적인 명세만으로 충분하기도 해서 해당 문서와 관련된 이해관계자 분들과 충분한 소통 후에 결정하고 있습니다.
도움이 되셨기를 바랍니다.
감사합니다. :)
1
2023. 08. 18. 20:36
안녕하세요, 인프런 AI 인턴이에요.
REST API의 예외 처리에 대한 응답 문서를 작성하는 방법에 대해 궁금하신 거죠? 예외 상황에 대한 응답을 문서로 작성하는 것은 좋은 방법입니다. 이를 통해 프로젝트에 참여하는 다른 인원들과 원활한 소통을 할 수 있을 거예요.
1번 케이스의 경우, 특정 API 문서마다 예외 상황에 대한 응답을 함께 작성하는 것이 좋은 방법입니다. 예를 들어, 아이디나 비밀번호가 틀렸을 때와 아이디가 존재하지 않을 때에 대한 예외 상황에 대한 응답을 해당 API의 문서에 자세히 작성해주시면 됩니다. 이렇게 함으로써 개별 API에 대한 응답 문서가 구체적이고 자세해져, 협업하는 다른 개발자들이 이해하기 쉬워집니다.
2번 케이스의 경우, 공통 예외 상황에 대한 처리를 문서의 별도 항목으로 작성하는 것도 좋은 방법입니다. 예를 들어, 인증 실패에 대한 응답을의 경우, 모든 인증 실패 상황에 대해 공통으로 동일한 401 코드를 반환하는 것이 좋다면, 이를 별도로 작성하여 프로젝트의 전반적인 예외 처리 항목에 기술해주시면 됩니다.
현업에서도 예외 발생 시 응답에 대한 문서를 작성하는 경우가 많이 있습니다. REST API의 예외 상황에 대한 응답 문서를 작성하여 다른 개발자들과의 소통을 원할하게 할 수 있습니다.
어떤 방식을 선택하더라도, 문서 가독성을 높이고 읽기 쉽게 작성하는 것이 중요합니다. 각각의 상황에 대한 응답을 명확하고 간결하게 작성하여 다른 개발자들이 이해하기 쉽도록 해야 합니다.
혹시 추가적인 도움이 필요하시다면, 더 자세한 내용이나 예시가 있다면 알려주세요. 도움을 드릴 수 있도록 최선을 다하겠습니다. 감사합니다.