API 문서는 개발자와 사용자가 원활하게 API를 파악하고 사용할 수 있도록 돕는 문서입니다. API 문서는 API의 기능을 분명하게 명시하고, 사용 방법과 관련 오류를 살펴볼 수 있게 해야 합니다.
일부 개발자들은 API 문서의 중요성을 간과하기도 합니다. 그러나 문서가 없다면 다른 사람들이 코드를 이해하는 데 많은 시간이 걸릴 것입니다. 개발자의 업무가 많은 경우에는 기술 문서를 작성하는 테크니컬 라이터가 이를 전문적으로 담당하기도 합니다.
오늘날 API 문서는 상품과 서비스의 일부로 간주되며 사용자 경험에도 중요한 영향을 미칩니다.
이번 글은 <Write the Docs>를 참고하였으며, API 문서를 작성하는 데 필요한 6가지 고려 사항을 담고 있습니다.
1. 개발을 시작하기 전에 문서를 작성하기
개발을 시작하기 전에 문서를 먼저 작성하는 것을 고려해보시기 바랍니다. 개발을 하지 않았는데 어떻게 문서를 작성할 수 있을까 싶지만, 해당 API가 어떤 기능을 할 것이며 이를 위해 사전에 필요한 사항들을 정리하는 것만으로도 유용합니다. 이를 통해 API 개발의 방향을 명확히 할 수 있으며, 문서 초안을 동료들에게 공유하고 피드백을 받을 수도 있습니다.
2. 두괄식으로 명시하기
API 문서의 첫 부분에는 해당 API가 정확히 어떤 작업을 위한 것인지 개괄적으로 명시해야 합니다. 이를 통해 문서에 접근한 이들은 해당 문서가 본인에게 필요한 것인지 판단할 수 있습니다.
또한 개발한 API 문서에는 아주 다양한 기능들이 포함되어 있을 것입니다. API 호출에 필요한 인증, 헤더 타입 등 이를 처음 보는 사용자가 어디서부터 어떻게 시작해야 하는지 기초적인 사항들을 도입부에서 설명하는 것이 좋습니다.
3. 문서를 읽는 대상자를 고려하기
API 문서를 읽는 대상은 크게 개발자와 사용자로 나눌 수 있습니다. 개발자와 사용자를 모두 고려하여 문서를 작성해야 합니다.
개발자들은 자신이 원하는 부분을 문서에서 빠르게 탐색하고 테스트하기를 원합니다. 이를 위해 일관적인 문서 구조와 예시를 제공할 필요가 있습니다. 세부 사항으로는 일관적인 헤딩 사용, 하이퍼링크 제공, 문단 나누기 및 리스트 활용을 고려할 수 있습니다.
사용자들의 수준은 초보에서 고급까지 다양할 수 있습니다. 초보 수준의 사용자를 염두에 두되 고급 사용자도 원하는 정보를 정확하게 얻을 수 있도록 해야 합니다. 즉, 필수적인 정보들을 정확하게 담되 가능한 쉬운 용어를 사용하는 것이 좋습니다. API 문서는 개발 지식이 없는 사람이 보더라도 이해할 수 있을 정도로 쉽고 간결하게 작성되어야 합니다.
4. 예시를 포함하기
대부분의 개발자들은 API 문서에서 안내하는 예시 코드를 복사 및 붙여넣기 하여 사용하기를 선호합니다. 이를 통해 테스트를 진행하고, 필요에 맞춰 수정해서 빠르게 사용할 수 있기 때문입니다. API의 핵심 엔드포인트를 테스트할 수 있는 예시를 제공하는 것이 좋습니다.
또한 응답 성공 예시와 에러 예시를 첨부해야 합니다 이 때 모든 에러가 아닌 가장 대표적인 에러들만 첨부하는 것이 좋습니다. 그렇지 않으면 문서가 너무 길어질 수 있습니다.
5. 좋은 API 문서 참고하기
이미 많은 기업들이 좋은 API 문서를 작성하여 제공하고 있습니다. 아래 사이트에 접속하여 좋은 API 문서로 언급되는 예시들을 참고해보실 수 있습니다.
- Stripe: https://stripe.com/docs
- Google: https://developers.google.com/gmail
6. 충분한 시간을 들이기
좋은 API 작성에는 시간이 필요합니다. API 문서는 개발자와 사용자를 위한 단순한 설명서가 아니라 상품의 일부이기도 합니다. API 작성을 위해 충분한 시간을 확보해야 합니다.
회사의 팀에서 일하고 있다면 다른 개발자 뿐만 아니라 기술 문서 작성자와 함께 문서에 대해 충분히 논의하는 것이 좋습니다. 만약, 팀 내부에서 문서를 이해하지 못하는 사람이 있다면 개선이 필요하다는 의미입니다.
API 문서는 한 번 작성하면 마무리 되는 작업이 아닙니다. 개발자와 사용자의 피드백을 반영하여 계속해서 문서를 업데이트해야 합니다
마치며
이상으로 좋은 API 문서 작성을 위한 사항들을 살펴봤습니다. 이를 정리하면 다음과 같습니다.
- 개발을 시작하기 전에 문서를 작성하기
- 두괄식으로 명시하기
- 문서를 읽는 대상을 고려하기
- 예시를 포함하기
- 좋은 API 문서 참고하기
- 충분한 시간을 들이기
