이 질문 뒤에 면접관이 확인하려는 것은 따로 있습니다.
팀 프로젝트에서 Spring REST Docs로 API 문서를 자동 생성한 경험이 있습니다. 처음엔 Swagger를 쓰다가 테스트 코드와 문서가 따로 관리되면서 실제 동작과 문서가 달라지는 문제가 생겼습니다. REST Docs는 테스트가 통과해야 문서가 생성되는 구조라 테스트 기반 문서화 방식이 이 문제를 해결해줬습니다. 초기 설정이 Swagger보다 번거로웠지만, 문서가 항상 실제 동작과 동기화된다는 신뢰가 팀 협업 품질을 높여줬습니다. 프론트엔드 개발자가 문서만 보고 연동 작업을 진행할 수 있게 됐고, 인터페이스 불일치로 생기는 커뮤니케이션 비용이 크게 줄었습니다. 지금도 문서화 도구는 작성 비용보다 유지 동기화 비용을 먼저 고려해서 선택합니다.
Spring REST Docs를 팀 프로젝트에 도입하면서 좋은 점만큼이나 어려운 부분도 있었습니다. Swagger는 코드에 어노테이션을 추가하면 바로 UI가 생겼는데, REST Docs는 테스트 코드를 먼저 짜야 문서가 생성되는 구조라 초기 세팅 시간이 더 걸렸습니다. API가 많아지면서 모든 엔드포인트의 테스트를 유지하는 것도 부담이 됐는데, 테스트가 없으면 문서가 갱신되지 않아 미구현 엔드포인트는 문서에 빠져 있는 경우도 생겼습니다. 생성된 문서 형태가 AsciiDoc 기반이라 프론트엔드 개발자에게 익숙하지 않아 처음에 읽는 방법을 안내해야 했습니다. 이런 한계에도 문서와 실제 동작이 다를 때 생기는 혼란을 경험한 입장에서는, 초기 비용을 치르더라도 동기화가 보장되는 구조가 나중에 유리하다는 것을 배웠습니다. 문서화 도구를 고를 때는 작성 편의성보다 팀이 오래 유지할 수 있는 구조인지를 먼저 봐야 한다는 것을 이 경험에서 배웠습니다.
Spring REST Docs를 처음 도입할 때 회원 가입 API의 테스트 코드를 먼저 작성했습니다. 요청 파라미터와 응답 필드를 문서로 남기려면 테스트 코드에서 각 필드를 명시적으로 기술해야 했는데, 이 과정에서 API 스펙을 다시 한 번 꼼꼼히 검토하게 됐습니다. 기존에 구현만 하고 넘어갔던 응답 필드 중 설명이 모호한 것들이 눈에 띄어, 문서화를 위해 스펙 자체를 명확히 하는 부수 효과가 있었습니다. 테스트가 통과하면 스니펫 파일이 생성되고, 이를 조합해 전체 API 문서로 만드는 흐름을 처음에는 번거롭게 느꼈는데 한 번 세팅하고 나니 반복 작업이 됐습니다. 새 API를 추가할 때마다 문서도 함께 생성되는 것이 자연스러운 습관이 됐고, 팀원이 문서를 보고 연동 작업을 진행하는 것을 보면서 문서화에 투자한 시간이 의미 있다는 것을 확인했습니다. 문서는 작성하는 사람이 아니라 읽는 사람을 위한 것이라는 것을 REST Docs를 직접 써보면서 실감했습니다.
답변에서 흔히 빠지는 것들 — 빠져 있으면 꼬리질문이 깊어집니다.
이 질문에 이어 부동산플래닛 백엔드 면접관이 던질 가능성이 높은 후속 질문.
이 페이지의 질문·답변·꼬리질문은 유사 직군 채용 시장의 공개된 면접 후기·커뮤니티 게시물을 분석해 구성한 학습 자료입니다. 특정 회사가 실제로 이 질문을 출제했다는 것을 보장하지 않으며, 모든 예시는 우문현답이 직접 작성한 창작물입니다. 해당 회사의 공식 입장과는 무관합니다. 회사 측의 정정 요청이 있을 경우 24시간 이내에 응답·수정합니다.