작은 API 문서부터 웹개발 코딩 루틴을 바꾼 과정

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

막히던 웹개발 실습을 API 문서로 다시 시작했습니다

코드보다 먼저 흐름을 적어본 이유

웹개발을 하다 보면 이상하게 코드보다 요청과 응답의 흐름에서 더 자주 막힙니다. 저도 처음에는 버튼을 누르면 서버에 저장되고, 다시 화면에 보이면 끝이라고 생각했지만 실제 프로젝트에서는 어떤 주소로 보내는지, 어떤 값이 필요한지, 실패했을 때 무엇을 보여줄지가 계속 발목을 잡았습니다.

그래서 최근 개인 프로젝트를 만들 때 코딩을 바로 시작하지 않고 작은 API 문서를 먼저 작성해 봤습니다. 거창한 문서화 도구를 쓴 것은 아니고, 노션 한 페이지와 간단한 표로 시작했습니다. 코딩은 컴퓨터가 이해할 수 있도록 절차를 설계하는 일이라는 설명은 코딩의 기본 정의와도 맞닿아 있습니다.

이 방식의 첫 장점은 개발 속도가 갑자기 빨라지는 것이 아니라, 헤매는 시간이 줄어든다는 점이었습니다. 특히 프론트엔드와 백엔드를 동시에 만지는 웹개발 입문자라면 코드 파일을 열기 전에 데이터의 이동 경로를 써보는 것만으로도 실수가 크게 줄어듭니다.

• 요청 주소: 예를 들어 /api/posts처럼 기능 단위로 적었습니다.
• 필요한 값: 제목, 본문, 작성자처럼 화면에서 보내야 할 데이터를 구분했습니다.
• 응답 형태: 성공 시 받을 값과 실패 시 보여줄 메시지를 미리 정했습니다.
• 확인 방법: 브라우저 콘솔, 네트워크 탭, API 테스트 도구 중 무엇으로 볼지 적었습니다.

처음부터 완벽한 문서를 만들려고 하면 또 다른 숙제가 됩니다. 저는 “내일의 내가 헷갈리지 않을 정도”를 기준으로 삼았을 때 가장 오래 유지됐습니다.

요청 하나를 적고 나니 코딩 순서가 눈에 보였습니다

화면부터 만들지 않고 데이터부터 잡았습니다

예전에는 웹개발을 시작하면 먼저 예쁜 화면을 만들고 싶었습니다. 입력창, 버튼, 카드 목록을 빠르게 배치하면 뭔가 완성되는 느낌이 들기 때문입니다. 하지만 실제로는 화면을 먼저 만든 뒤 데이터 구조를 바꾸면서 이름을 계속 고치고, 컴포넌트도 다시 쪼개는 일이 많았습니다.

API 문서를 먼저 적자 코딩 순서가 달라졌습니다. “게시글 작성” 기능이라면 화면, 서버, 데이터베이스를 따로 보지 않고 사용자가 입력한 값이 어디로 가서 어떤 형태로 돌아오는지부터 생각하게 됐습니다. 덕분에 변수명도 덜 흔들리고, 상태 관리도 훨씬 단순해졌습니다.

제가 실제로 사용한 순서는 아래와 같습니다. 이 흐름은 작은 토이 프로젝트뿐 아니라 팀 프로젝트에서도 꽤 유용했습니다. 특히 초보 개발자가 “이제 뭘 해야 하지?”라고 멈춰서는 순간을 줄여줍니다.

1. 화면에서 필요한 사용자 행동을 한 문장으로 씁니다.
2. 그 행동에 필요한 입력값을 표로 정리합니다.
3. 서버에 보낼 요청 주소와 HTTP 메서드를 정합니다.
4. 성공 응답과 실패 응답 예시를 각각 적습니다.
5. 그다음 컴포넌트, 함수, 파일 구조를 나눕니다.

작은 예시가 가장 강력했습니다

문서에는 긴 설명보다 예시 JSON 하나가 더 도움이 됐습니다. 예를 들어 게시글 생성 기능이라면 title, content, category 같은 필드를 실제 값처럼 채워 넣었습니다. 그러면 프론트엔드에서 폼 이름을 무엇으로 둘지, 백엔드에서 유효성 검사를 어디에 넣을지 자연스럽게 보입니다.

• 좋았던 점: 코딩 전에 빠진 값을 발견할 수 있었습니다.
• 아쉬운 점: 처음에는 문서 작성이 개발을 늦추는 일처럼 느껴졌습니다.
• 추천 상황: 로그인, 게시판, 결제 전 단계처럼 데이터 흐름이 있는 기능에 특히 잘 맞았습니다.

브라우저 개발자 도구와 함께 보니 오류가 덜 무서웠습니다

네트워크 탭을 문서와 대조했습니다

API 문서를 써도 실제 코딩에서는 오류가 납니다. 다만 차이가 있다면 오류를 추측으로 쫓아가지 않게 된다는 점입니다. 저는 브라우저 개발자 도구의 네트워크 탭을 열어두고, 문서에 적은 요청 주소와 실제 요청이 같은지 먼저 확인했습니다.

예전에는 에러 메시지가 나오면 검색창부터 열었습니다. 지금은 먼저 요청 메서드가 맞는지, 보낸 데이터 이름이 문서와 일치하는지, 응답 코드가 무엇인지 확인합니다. 이 습관 하나만으로도 웹개발 디버깅 시간이 꽤 줄었습니다.

프로그래밍은 단순히 문법을 외우는 일이 아니라 문제를 작은 절차로 나누어 처리하는 활동입니다. 더 넓은 개념 설명은 프로그래밍의 의미를 참고하면 입문 단계에서 방향을 잡는 데 도움이 됩니다.

• 404 오류: 주소가 문서와 다른지 먼저 봤습니다.
• 400 오류: 필수 입력값이 빠졌거나 이름이 다른 경우가 많았습니다.
• 401 오류: 로그인 토큰이나 인증 헤더를 확인했습니다.
• 500 오류: 서버 로그와 요청 본문을 함께 비교했습니다.

에러를 빨리 없애는 사람보다, 에러가 어디서 시작됐는지 좁혀가는 사람이 더 안정적으로 성장합니다.

도구를 늘리기보다 문서 형식을 줄였을 때 유지가 쉬웠습니다

제가 써본 방식의 장단점

처음에는 API 문서라고 하면 전문 도구부터 떠올렸습니다. 실제 협업에서는 Swagger, Postman, Bruno 같은 도구가 도움이 될 수 있습니다. 하지만 개인 학습이나 작은 웹개발 프로젝트에서는 도구 자체를 배우느라 정작 코딩 흐름을 놓칠 때도 있었습니다.

제가 가장 오래 쓴 방식은 단순한 표였습니다. 엔드포인트, 메서드, 요청값, 응답값, 메모 다섯 칸만 만들었습니다. 이 정도면 부담이 적고, 기능이 바뀌어도 바로 고칠 수 있습니다. 무료 문서 앱이나 마크다운 파일이면 충분했고, 유료 협업 도구는 팀 규모가 커진 뒤 고려해도 늦지 않았습니다.

다만 단순한 방식에도 단점은 있습니다. 자동 테스트와 연결되지 않으니 문서가 낡을 수 있고, 여러 사람이 동시에 작업하면 최신 상태를 맞추기 어렵습니다. 그래서 저는 “코드를 바꾼 사람이 문서 한 줄도 같이 고친다”는 규칙을 작게 정했습니다.

• 마크다운: 빠르고 가볍지만 표가 길어지면 읽기 불편했습니다.
• 스프레드시트: 필드가 많은 API를 비교하기 좋았습니다.
• API 테스트 도구: 실제 요청을 저장해 재사용하기 편했습니다.
• 자동 문서화: 팀 프로젝트에서는 좋지만 초기 설정 시간이 필요했습니다.

표 하나로 충분했던 기준

제가 느낀 적정선은 “설명은 짧게, 예시는 구체적으로”였습니다. 설명을 길게 쓰면 금방 안 읽게 되고, 예시가 없으면 코딩할 때 다시 추측하게 됩니다. 그래서 각 API마다 성공 예시와 실패 예시를 하나씩만 남겼습니다.

• 개인 프로젝트라면 한 페이지 문서로 시작합니다.
• 팀원이 둘 이상이면 변경 날짜와 담당자를 적습니다.
• 배포 전에는 문서의 요청 예시를 실제 서버에 한 번씩 보내봅니다.

AI 코딩 도구에 붙여 넣었을 때 차이가 더 크게 났습니다

프롬프트가 짧아지고 결과가 안정됐습니다

요즘 웹개발에서는 AI 코딩 도구를 함께 쓰는 일이 자연스러워졌습니다. 저도 컴포넌트 초안, 테스트 케이스, 에러 원인 추적에 도움을 받습니다. 그런데 막연히 “게시판 만들어줘”라고 요청할 때보다, 제가 작성한 API 문서를 함께 넣었을 때 결과가 훨씬 안정적이었습니다.

특히 요청값과 응답값이 정리돼 있으면 AI가 임의로 필드 이름을 만들 가능성이 줄었습니다. 예전에는 title인지 subject인지, userId인지 authorId인지 매번 섞여서 수정 시간이 생겼습니다. 문서를 먼저 넣으니 코딩 결과물이 제가 만든 구조에 더 잘 맞았습니다.

기업 환경에서도 AI 코딩 활용은 계속 넓어지고 있습니다. 예를 들어 폐쇄망 환경에서의 코딩 지원 사례를 다룬 관련 기술 기사를 보면, 앞으로 개발자의 역할은 코드를 대신 쓰게 하는 것보다 맥락을 정확히 제공하는 능력에 가까워질 가능성이 큽니다.

• 잘 먹힌 요청: “이 API 문서를 기준으로 React 폼 컴포넌트를 만들어줘.”
• 덜 먹힌 요청: “게시판 기능 예쁘게 만들어줘.”
• 효과가 컸던 부분: 타입 정의, 입력 검증, 에러 메시지 분기였습니다.
• 주의할 점: AI가 만든 코드는 반드시 실제 요청으로 확인해야 했습니다.

제가 쓰는 짧은 프롬프트 형식

프롬프트도 길게 꾸밀 필요가 없었습니다. 기능 목적, API 문서, 원하는 기술 스택, 제한 조건 네 가지를 넣으니 충분했습니다. “기존 코드 스타일을 유지해 달라”는 문장을 추가하면 불필요한 구조 변경도 줄어들었습니다.

1. 먼저 기능의 목표를 한 문장으로 씁니다.
2. API 문서 표나 예시 JSON을 붙입니다.
3. 사용 중인 프레임워크와 상태 관리 방식을 밝힙니다.
4. 수정 범위와 만들지 말아야 할 것을 함께 적습니다.

모든 프로젝트에 문서부터 쓰는 방식이 맞지는 않았습니다

너무 작은 실습에서는 손이 느려질 수 있습니다

API 문서를 먼저 쓰는 방식이 늘 정답은 아니었습니다. 아주 작은 코딩 실습, 예를 들어 버튼 클릭으로 색을 바꾸거나 배열 메서드를 연습하는 수준에서는 문서화가 오히려 흐름을 끊었습니다. 이런 경우에는 바로 코드를 치면서 감각을 익히는 편이 더 좋았습니다.

또 아이디어가 아직 흐릿한 초기 실험에서는 문서가 너무 빨리 굳어지는 느낌도 있었습니다. 화면을 만지다 보면 기능 자체가 바뀌는데, 처음 적은 API 구조에 억지로 맞추려다 더 복잡해진 적도 있습니다. 그래서 저는 지금은 프로젝트 성격에 따라 문서의 양을 조절합니다.

반대 관점도 충분히 설득력이 있습니다. 어떤 개발자는 “먼저 만들어봐야 진짜 요구사항이 보인다”고 말합니다. 저도 동의합니다. 다만 로그인, 저장, 조회, 수정처럼 데이터가 오가는 웹개발 기능이라면, 적어도 요청과 응답 예시 한 줄은 적어두는 쪽이 나중의 나를 덜 괴롭혔습니다.

• 바로 코딩해도 좋은 경우: 문법 연습, UI 효과 실험, 알고리즘 풀이입니다.
• 문서부터 쓰면 좋은 경우: 회원 기능, 게시판, 관리자 화면, 외부 API 연동입니다.
• 절충안: 처음에는 메모 5줄만 쓰고, 기능이 굳어지면 표로 바꿉니다.
• 제가 남긴 기준: 데이터가 서버로 간다면 문서화하고, 화면 안에서만 끝나면 바로 실험합니다.

빠른 코딩과 느린 설계 사이에서 잡은 균형

결국 이 후기는 “문서를 많이 쓰자”가 아니라 “헷갈리는 지점을 먼저 보이게 하자”에 가깝습니다. 웹개발에서 코딩 실력은 손이 빠른 것만으로 결정되지 않았습니다. 어디까지 정하고 시작해야 하는지, 어디부터 열어두어야 하는지 감각을 익히는 일이 더 오래 남았습니다.

• 기능 이름을 한 문장으로 말할 수 없으면 코딩 전에 더 생각합니다.
• 요청값을 적지 못하면 화면 입력부터 다시 봅니다.
• 응답값을 상상하지 못하면 사용자에게 보여줄 상태가 빠진 것입니다.