Showing Posts From

미뤘다가

14 Dec, 2025
- 코드리뷰

API 문서화를 미뤘다가 생기는 혼란

문서화는 나중에 API 개발 끝났다. 배포도 했다. 근데 문서는 안 썼다. "나중에 쓰지 뭐." 그게 3주 전이다. 이제 슬랙이 난리다. "김개발님 이 API 파라미터가 뭐예요?" "응답 형식이 어떻게 되죠?" "에러코드 정리된 거 있어요?" 코드 보면 되는데. 근데 그것도 민망하다.처음엔 괜찮았다 처음 2주는 괜찮았다. 나만 쓰는 API였으니까. 인증 토큰은 헤더에 Authorization: Bearer {token}. 페이징은 page랑 size. 정렬은 sort. 당연한 거 아닌가. 근데 프론트팀 신입이 들어왔다. 김신입. "김개발님, API 명세서 어디 있어요?" "아... 그게... 코드 보면 돼요." "네? 코드요?" 말하면서도 개같다는 걸 알았다. 질문이 쌓인다 김신입은 착하다. 슬랙으로 물어본다. 하나씩. "User API의 role 필드 값이 뭐가 올 수 있나요?" "ADMIN, USER, GUEST 세 개요." 10분 후. "null일 수도 있나요?" "아뇨. 필수값이에요." 또 10분. "그럼 기본값은 뭐예요?" "기본값 없어요. 회원가입 때 지정해야 해요." 한 필드에 세 번 물었다. 나는 코드 짜다 말고 세 번 답했다.그냥 코드 보라고 할까 "코드 보면 다 나와요." 이렇게 말하고 싶다. 근데 그게 개발자 오만이라는 걸 안다. 코드가 문서는 아니니까. 프론트 개발자가 스프링 코드 뒤적이면서 @RequestBody가 뭔지 찾아보고, @Valid 어노테이션 의미 파악하고, 유효성 검증 로직 추적하고... 그건 폭력이다. 근데 문서 쓰는 것도 폭력이다. 나한테. 회의에서 터졌다 기획자 박기획이 말했다. "이번 기능, API 호출 시나리오 정리 좀 해주세요." "시나리오요?" "네. 어떤 순서로 어떤 API 호출하는지요. 플로우차트 같은 거." "그건... QA팀이 테스트하면서 보면 되는 거 아닌가요?" "QA도 모르는데요. 문서가 없어서." 회의실이 조용해졌다. 다들 나를 봤다. 나는 모니터 보면서 펜 돌렸다. "...알겠습니다."일단 미뤘던 이유 문서화를 안 한 게 게을러서만은 아니다. 변명이긴 한데, 진짜다. API가 계속 바뀌었다. 초기 개발 단계라서. 처음엔 User 조회가 GET /user/{id}. 근데 기획 바뀌어서 GET /users/{id}로 수정. 복수형. 응답 형식도 바뀌었다. 처음엔 유저 객체 그대로 내려줬는데, 나중에 래핑해서 { data: {...}, meta: {...} } 형태로. 에러 코드는 3번 바뀌었다. USER_NOT_FOUND가 USER_001이 됐다가 다시 ERR_USER_NOT_FOUND로. 그때마다 문서 고치려면 개빡친다. 그래서 "일단 완성되면 쓰지" 했는데. 완성은 안 된다. 계속 수정된다. 코드로 자동 생성? "Swagger 쓰세요." 후배 이후배가 말했다. "Swagger요?" "네. 어노테이션 달면 문서 자동 생성돼요." 알긴 아는데. 도입이 귀찮다. 어노테이션 달려면 컨트롤러마다 @ApiOperation, @ApiParam 다 붙여야 한다. 우리 API 엔드포인트가 47개다. 기존 코드 47개 파일 열어서 어노테이션 추가. 그것도 일이다. "시간 나면 해볼게요." 이후배는 더 안 물었다. "시간 나면"이 뭔 뜻인지 아니까. 문서 쓰기 시작했다 결국 썼다. Notion 페이지 만들었다. "API 문서" 제목 달고. 목차 만들고.인증 User API Post API Comment API ...47개 엔드포인트를 정리하기 시작했다. 각 API마다:메서드, URL 요청 파라미터 요청 바디 예시 응답 예시 에러 케이스첫 번째 API 정리하는 데 30분 걸렸다. "30분 곱하기 47... 2350분... 39시간?" 계산기 두드리다가 한숨 나왔다. 누가 봐주긴 할까 4시간 정도 쓰고 12개 API 문서화했다. 진도는 25%. 슬랙에 공유했다. "API 문서 작성 시작했습니다. 피드백 주세요." 5분 후 김신입이 답장했다. "오오 감사합니다!" 그게 끝이다. 다른 반응은 없다. "이거 진짜 다 쓸 가치가 있나?" 혼잣말이 나왔다. 근데 김신입이 질문이 확 줄었다. 슬랙 알림이 조용하다. 그거면 됐다. 유지보수가 문제다 이틀 뒤 기획 변경됐다. User API에 nickname 필드 추가. 필수값. 2~10자. 코드는 10분 만에 고쳤다. 근데 문서는? Notion 열어서 User API 섹션 찾아서. 요청 바디 예시 수정하고. 응답 예시 수정하고. 유효성 검증 규칙 추가하고. 15분 걸렸다. "이래서 안 쓰는 건데." 또 혼잣말. 그리고 1주일 뒤 또 기획 변경. 이번엔 문서 업데이트 안 했다. "나중에 몰아서 하지." 3주 전 그 마인드가 돌아왔다. 문서가 틀렸다 김신입이 또 물었다. "문서랑 실제 API 응답이 달라요." "어디요?" "nickname 필드가 안 내려와요." "아, 그거 선택값으로 바뀌었어요." "문서에는 필수라고 돼있는데..." "...업데이트 깜빡했네요." 이게 더 최악이다. 문서가 없는 것보다 틀린 문서가 더 위험하다. 김신입은 틀린 문서 믿고 개발했다. 필수값이니까 예외처리 안 했다. 버그 났다. 내 잘못이다. Swagger를 결국 도입했다 주말에 했다. 집에서. Spring REST Docs도 고민했는데, 테스트 코드 짜야 해서 패스. Swagger가 빠르다. 의존성 추가. 설정 파일 작성. 컨트롤러에 어노테이션 추가. @ApiOperation(value = "유저 조회", notes = "ID로 유저 조회") @ApiResponses({ @ApiResponse(code = 200, message = "성공"), @ApiResponse(code = 404, message = "유저 없음") }) @GetMapping("/users/{id}") public UserResponse getUser(@PathVariable Long id) { ... }이런 식으로 47개 엔드포인트 다 달았다. 토요일 오후 내내. 근데 뭔가 뿌듯하다. 코드 정리하니까 보기 좋다. /swagger-ui.html 접속해봤다. 문서가 예쁘게 나온다. "이거 괜찮네." 팀원들 반응 월요일에 공유했다. "Swagger 도입했습니다. /swagger-ui.html 확인해보세요." 김신입 답장이 빨랐다. "헐 대박이에요!" 이후배도 반응했다. "오 형 주말에 이거 하신 거예요?" "그냥 심심해서요." 사실 김신입이 계속 물어볼까봐 불안해서 한 거다. 기획자 박기획도 봤다. "이거 좋네요. 이제 기획 전달할 때 이거 보여드리면 되겠어요." 개발 안 하는 사람도 보기 쉽다는 게 Swagger 장점이다. 그래도 완벽하진 않다 Swagger도 한계는 있다. 복잡한 비즈니스 로직 설명은 어렵다. 어노테이션만으로는. "결제 API는 먼저 주문 생성하고, 그 다음 결제 요청하고..." 이런 플로우 설명은 못한다. 에러 케이스 설명도 부족하다. 400 에러가 나는 이유가 10가지인데, 그걸 다 @ApiResponse에 못 쓴다. 인증 토큰 발급 과정, 리프레시 토큰 로직... 이런 건 별도 문서 필요하다. 결국 Swagger + Notion 병행하게 됐다. Swagger는 API 레퍼런스. Notion은 가이드 문서. 둘 다 관리하는 건 귀찮은데. 그래도 없는 것보단 낫다. 유지보수는 여전히 숙제 한 달 지났다. Swagger 문서도 낡아간다. 신규 API 추가할 때 어노테이션 빼먹는다. 급하니까. "나중에 추가하지." 그러고 까먹는다. 김신입이 또 물어본다. "새로 추가된 알림 API 문서는 어디 있어요?" "아... 어노테이션 추가 안 했네요. 코드 보면..." 또 "코드 보면"이 나왔다. 문서화는 일회성이 아니다. 계속 관리해야 한다. 그게 어렵다. PR 체크리스트에 추가 이후배가 제안했다. "PR 템플릿에 문서 업데이트 항목 추가하는 거 어때요?" "PR 템플릿에요?" "네. API 변경 시 Swagger 어노테이션 업데이트했는지 체크하는 거요." ## Checklist - [ ] 테스트 코드 작성 - [ ] API 변경 시 Swagger 문서 업데이트 - [ ] 코드 리뷰 반영괜찮은 아이디어다. 실제로 추가했다. 다들 체크는 한다. 안 하면 내가 코멘트 달아준다. "Swagger 문서 업데이트 부탁드려요." 처음엔 귀찮아했는데, 한 달 지나니 습관 됐다. 신규 API 만들 때 자동으로 어노테이션 단다. 이제는. 문서화 문화 결국 문화 문제다. "문서화는 나중에" 이 마인드가 문제였다. 개발하면서 동시에 문서 작성. 이게 기본이 돼야 한다. 근데 그게 쉽지 않다. 특히 일정 촉박할 때. "기능 개발이 먼저고 문서는 나중에" 이 생각이 자동으로 나온다. 팀장이 "문서화도 개발의 일부"라고 강조한다. 맞는 말인데. 실천이 어렵다. 지금도 완벽하진 않다. 그래도 3달 전보단 낫다. 배운 것들 API 개발하고 문서 안 쓰면:팀원이 계속 물어본다. 슬랙 알림 지옥. 신입이 헤맨다. 온보딩 시간 3배. 기획/QA가 답답해한다. "이거 어떻게 테스트해요?" 나도 까먹는다. 3개월 전 API 뭐였는지 기억 안 남.문서화 방법:Swagger/OpenAPI: API 레퍼런스용, 자동 생성 가능 Notion/Wiki: 가이드, 플로우, 비즈니스 로직 설명 README: 빠른 시작 가이드 코드 주석: 복잡한 로직만중요한 건 도구가 아니라 습관이다. 개발 끝나고 "나중에 쓰지"가 아니라, 개발하면서 바로 쓰기. PR 체크리스트에 넣기. 리뷰 때 확인하기. 완벽하지 않아도 된다. 없는 것보단 낫다. 3개월 후 효과 문서화 시작하고 3개월 지났다. 김신입 질문이 80% 줄었다. 슬랙 조용하다. 신규 입사자 온보딩 시간 절반 됐다. Swagger 보고 바로 개발 시작. QA팀이 좋아한다. "이제 테스트 케이스 짜기 쉬워요." 나도 편하다. "코드 보면 돼요" 안 해도 된다. 시간 투자는 했다. 주말 하루, 그 뒤로 일주일에 1시간씩. 근데 그거 하고 절약되는 시간이 더 크다. 질문 답하는 시간, 설명하는 시간, 디버깅 도와주는 시간. "진작 할 걸" 이 생각 든다. 여전히 귀찮다 그래도 솔직히 말하면. 여전히 귀찮다. API 하나 추가할 때마다 Swagger 어노테이션 5줄 쓰는 거. 귀찮다. Notion 가이드 문서 업데이트하는 거. 귀찮다. 기획 변경될 때마다 문서 수정하는 거. 귀찮다. 근데 한다. 안 하면 더 귀찮아지니까. 김신입이 또 물어보는 게 더 귀찮다. 틀린 문서 때문에 버그 나는 게 더 귀찮다. 문서화는 미래의 나를 위한 투자다. 그리고 팀을 위한 배려다. 개발자가 코드만 짜면 된다는 생각. 학생 때 끝났어야 했다. 실무에서는 커뮤니케이션도 개발이다. 문서도 개발이다."나중에"는 영원히 안 온다. 지금 쓰거나, 계속 물어봐 주거나.