API 문서 전달을 어떻게 해야 프론트와 협업에 좋을까

백엔드에서 API를 만들고 프론트에 전달할 때, 처음에는 Swagger 주소 하나 보내주면 끝난다고 생각하기 쉽습니다.
저도 한동안은 그랬습니다. 엔드포인트, 파라미터, 응답 스키마가 다 보이니 충분하다고 느꼈습니다.

그런데 실제 협업에서는 문서가 있어도 막히는 일이 계속 생겼습니다.
프론트가 이해하지 못한 건 "이 필드가 string인지 long인지"보다, 언제 이 응답이 오고 어떤 에러를 고려해야 하는지 같은 운영 맥락이었습니다.

결국 API 문서는 명세만 정리하는 문서가 아니라, 협업 비용을 줄이는 문서라는 쪽으로 생각이 바뀌었습니다.

Swagger만으로는 자꾸 빠지는 정보가 있었다

Swagger는 분명 유용합니다.
요청 필드와 응답 구조를 빠르게 확인할 수 있고, 테스트도 바로 해볼 수 있습니다.

하지만 아래 정보는 Swagger만으로는 자주 부족했습니다.

실무에서는 이 네 가지가 빠질수록 채팅과 회의가 늘어났습니다.

협업이 가장 안정적이었던 방식은 문서를 하나로 해결하려 하기보다, 역할을 나눠서 전달하는 방식이었습니다.

이렇게 나누고 나니 문서가 오히려 덜 복잡해졌습니다.
Swagger는 기계적으로 정확해야 하고, 협업 문서는 사람이 읽기 쉬워야 하고, 변경 이력은 짧고 빠르게 전달돼야 했기 때문입니다.

프론트와 협업할 때 제일 도움이 됐던 건 완벽한 스키마 정의보다, 실제 화면에서 보게 될 응답 예시였습니다.

예를 들어 아래 정보가 같이 있으면 구현 속도가 확실히 달랐습니다.

특히 목록 API나 상세 API는 "빈 배열인지", "null인지", "필드가 아예 없는지"에 따라 프론트 처리 방식이 달라져서, 이 부분을 문서에 분명히 적는 편이 좋았습니다.

실무에서 자주 놓치는 부분이 에러 응답입니다.
성공 응답은 열심히 맞춰도, 실패 응답은 대충 message 하나 적어두고 넘어가는 경우가 많습니다.

그런데 프론트 입장에서는 오히려 에러 처리가 더 중요했습니다.

그래서 저는 에러 코드를 화면 기준으로 묶어 설명하는 문서를 따로 두는 편이 좋다고 봅니다.
Swagger에 에러 스키마가 있더라도, 협업 문서에 "이 에러는 어떤 순간에 오는가"를 같이 적는 편이 훨씬 도움이 됐습니다.

문서보다 더 자주 놓치는 건 변경 공지였습니다.
API가 이미 구현되어 있더라도, 필드 하나가 추가되거나 nullable 정책이 바뀌는 순간 프론트는 바로 영향을 받습니다.

그래서 지금은 변경 이력을 아래처럼 짧게 남깁니다.

이걸 슬랙이나 협업 문서에 같이 남기면 "문서에는 있었는데 못 봤다"는 상황이 꽤 줄었습니다.

아무리 잘 정리된 문서도 코드와 어긋나기 시작하면 바로 신뢰를 잃습니다.
문서가 오래되면 프론트는 결국 Swagger 테스트나 실제 호출 결과를 더 믿게 되고, 그러면 문서는 형식적인 산출물에 가까워집니다.

그래서 지금은 문서 양보다도 아래를 더 중요하게 봅니다.

문서는 한 번 잘 만드는 것보다, 계속 같이 고치는 습관이 더 중요했습니다.

좋은 API 문서는 설명이 많은 문서가 아니라, 프론트가 질문하기 전에 필요한 정보를 먼저 주는 문서에 가깝습니다.

실무에서는 Swagger 주소 하나보다, 예시 응답 + 에러 코드 + 변경 이력까지 같이 전달할 때 협업이 훨씬 부드러웠습니다.
저도 결국 API 문서를 백엔드 산출물이 아니라, 프론트와 같이 쓰는 작업 문서로 보게 됐습니다.