정확한 타입 생성
schema가 정확하면 프론트 타입과 SDK 생성 품질이 좋아집니다.
이 파트에서 다루는 내용
CH 13 문서가 곧 산출물이 되는 구조CH 14 AI 도구와 API 문서 연동
01
API 문서는 신규 투입자의 첫 기준점입니다
잘 정리된 API 문서는 단순 참고자료가 아닙니다. 인수인계 상황에서 신규 투입자가 가장 먼저 찾는 기준점이고, 협업 중 반복 질문을 줄여주는 공통 언어입니다.
포트폴리오 관점에서도 내가 어떤 API를 어떤 기준으로 설계했는지 보여주는 문서는 코드 일부보다 설계 역량을 빠르게 보여줍니다.
산출물 관점
Git 커밋 히스토리가 작업 과정의 증거라면, API 문서는 설계 사고의 증거입니다.
02
AI 도구는 OpenAPI 스펙을 입력값으로 활용합니다
OpenAPI 스펙은 사람만 읽는 문서가 아니라 AI 도구가 직접 읽고 활용하는 입력값이기도 합니다. 정확한 스펙이 있으면 클라이언트 코드, 타입, 테스트 초안을 더 정확하게 만들 수 있습니다.
반대로 기존 라우트 코드에서 OpenAPI 초안을 뽑아낸 뒤 사람이 검수하는 흐름도 가능합니다. 중요한 것은 AI가 만든 초안도 계약 문서이므로 사람이 최종 확인해야 한다는 점입니다.
테스트 초안 생성
상태 코드와 에러 응답이 명확하면 테스트 케이스도 구체적으로 만들 수 있습니다.
리뷰 비용 절감
모호한 설명보다 구조화된 스펙이 사람과 AI 모두에게 더 좋은 입력입니다.
03
완성 기준은 실제 협업에 쓸 수 있는가입니다
- Swagger UI URL 또는 스펙 파일 위치가 README나 온보딩 문서에 명시되어 있습니다.
- 주요 API에 요청 파라미터, 성공 응답, 대표 에러 응답, 인증 여부가 포함되어 있습니다.
- Breaking Change 판단 기준과 변경 이력 위치가 정해져 있습니다.
- 프론트와 백엔드가 같은 스펙을 보고 개발할 수 있습니다.
04
프로젝트 팀원은 Swagger를 실행 가능한 계약으로 읽습니다
팀원이 API 문서를 볼 때는 설명 문구만 읽는 것이 아니라 실제 화면이나 기능에서 어떤 요청을 보내야 하는지 확인해야 합니다. endpoint, method, required parameter, 인증 여부, 성공 응답, 대표 에러 응답을 한 묶음으로 봅니다.
Swagger UI의 Try it out은 편하지만 운영 데이터에 쓰기 요청을 보낼 수 있으므로 대상 서버와 권한을 먼저 확인합니다. 개발 서버에서 요청을 재현하고, 응답이 스펙과 다르면 문서 문제인지 구현 문제인지 분리해야 합니다.
요청 전 확인
서버 환경, 인증 토큰, 필수 path/query/body 값, 쓰기 요청 여부를 먼저 확인합니다.
응답 비교
상태 코드, 응답 필드, nullable 여부, 에러 포맷이 스펙과 실제 응답에서 같은지 봅니다.
변경 감지
PR에서 schema required, enum, field type, status code가 바뀌면 프론트와 연동 코드 영향이 있는지 확인합니다.
팀원이 API 응답을 직접 확인하는 최소 명령bash
curl -i http://localhost:3000/openapi.json
curl -i http://localhost:3000/products
curl -i -H "Authorization: Bearer <token>" http://localhost:3000/products첫 줄은 스펙 제공 여부, 둘째 줄은 공개 API, 셋째 줄은 인증 API 확인 예시입니다.
사용자 기준
API 문서를 쓰는 팀원은 Swagger UI가 보이는지보다 이 문서만 보고 안전하게 요청을 만들 수 있는지를 기준으로 봐야 합니다.
체크