개발자가 첫날부터 따라할 수 있는 명확한 API 문서를 작성해 드립니다

대부분의 API 문서가 실패하는 이유

엔드포인트를 설명하고 사람들이 실제로 막히는 부분(인증 방법, 현실적인 요청 모습, 오류의 의미, 해결 방법)을 건너뜁니다. 그러면 독자는 지원 티켓을 열게 되는데, 이는 문서가 제거해야 할 비용입니다.

작성 방법

기억이 아닌 소스에서 가져옵니다. 경로, 유효성 검사 계층 및 오류 핸들러를 읽은 다음 실제 자격 증명으로 API를 직접 호출합니다. 문서의 모든 예시는 제가 만든 요청과 받은 응답입니다. 가상의 페이로드나 엔드포인트가 반환하지 않는 상태 코드는 없습니다.

문서 내용

• 인증: 토큰 획득, 갱신, 세션 도중 만료 시 발생하는 상황.
• 매개변수, 완전한 예시 요청, 실제 응답 형태를 포함한 모든 엔드포인트.
• 각 오류 코드를 원인 및 해결책에 매핑하는 오류 참조(메시지만 반복하는 것이 아님).
• 새로운 개발자가 10분 이내에 성공적인 호출을 할 수 있도록 안내하는 시작 경로.
• 실제로 적용되는 경우에 대한 속도 제한, 페이지 매김, 웹훅 및 멱등성 설명.

형식

저장소의 마크다운, OpenAPI 또는 문서 사이트에 맞게 구조화됨 — 실제로 유지보수할 수 있는 형식으로 제공됩니다. 사용자가 문의하는 언어로 된 코드 샘플은 실행하여 확인됩니다. 원하시면 Postman 또는 유사한 컬렉션이 포함됩니다.

필요한 것

저장소 액세스 또는 OpenAPI 파일, 테스트 환경을 위한 작동하는 자격 증명 하나, 그리고 지원팀이 답변하기 지쳐하는 모든 질문. 이 질문들이 개요가 됩니다.

포함되지 않음

마케팅 문구. 이 문서는 소프트웨어가 정확히 무엇을 하는지 문서화합니다. 랜딩 페이지는 다른 기술입니다.

처리 시간 및 커뮤니케이션

첫 번째 완전한 초안은 일반적으로 일주일 이내에 도착하며, 귀하의 지원팀이 계속 답변하는 질문에 대해 검토합니다. 저는 다듬어졌지만 틀린 것을 제공하는 것보다 엣지 케이스를 아는 엔지니어에게 일찍 수정받는 것을 선호합니다. 최종 문서의 모든 예시는 귀하의 API에 대해 실행되었으므로, 그 안에 있는 어떤 것도 희망 사항이 아닙니다.