API 문서 완성도, 어떤 기준으로 점수를 매길까?
좋은 API 문서는 개발자가 별도 문의 없이도 바로 연동할 수 있게 해줍니다. 이 계산기는 실제로 개발자들이 API 문서에서 가장 자주 찾는 8가지 요소를 체크리스트로 구성해, 문서의 완성도를 100점 만점으로 점수화합니다.
가장 배점이 높은 항목은 엔드포인트 설명, 요청/응답 예시, 파라미터 명세, 에러 코드 설명으로 각각 15점씩 배정되어 있습니다. 이 네 가지는 개발자가 실제로 API를 호출해보기 전에 반드시 확인하는 정보이기 때문입니다. 인증 방법, Rate Limit 정책, Changelog, Try it out 기능은 각 10점으로 상대적으로 낮게 배정했지만, 프로덕션 연동 단계에서는 여전히 중요한 요소입니다.
점수가 60점 미만이라면 개발자들이 문의를 자주 남기거나 잘못된 방식으로 API를 호출할 가능성이 높습니다. 배점이 높은 항목부터 순서대로 보완하면 가장 효율적으로 문서 품질을 끌어올릴 수 있습니다.
자주 묻는 질문
이 체크리스트가 모든 API 문서에 적용되나요?
REST, GraphQL 등 대부분의 API 문서 형태에 공통적으로 적용되는 항목으로 구성했습니다. 다만 내부용 API는 일부 항목을 완화해서 적용해도 괜찮습니다.
Try it out 기능이 없으면 점수가 크게 낮아지나요?
10점만 차감되므로 다른 7개 항목을 모두 충족하면 90점을 받을 수 있습니다. 실제 호출 테스트 기능은 우선순위가 상대적으로 낮은 항목입니다.
점수가 낮으면 어떤 항목부터 개선해야 하나요?
배점이 높은 요청/응답 예시, 파라미터 명세, 에러 코드 설명을 먼저 채우는 것이 문서 사용성 개선에 가장 효과적입니다.