API Documentation

API Documentation

Examples

• Google Maps API
• Stripe API -- Super Strong!

Good API Documentation

좋은 API 문서는 API를 고려하는 개발자가 API의 목적, API가 작동하는 데이터, 요청을 보내고 응답을 분석하는 방법을 신속하게 이해할 수 있도록 해준다.

좋은 API 문서에 포함되는 주된 요소들

• Introduction

  • What is your API doing, what is it about, why did you create it...

• Getting Started

  • Base URL
  • API Keys/Authentication(if applicable)

• Errors

  • Response codes
  • Messages
  • Error types

• Resource endpoint library

  • Organized by resource
  • Include each endpoint
  • Sample request
  • Arguments including data types
  • Response object including status codes and data types
  
  

Project Documentation

모든 우수하고 문서화된 프로젝트에는 프로젝트를 이용하거나 프로젝트에 기여하고자하는 개발자에게 프로젝트를 어떻게 시작할 것인지 명확하게 설명해야 하는 README.md 파일이 있다. 개인이 선호하는 스타일과 프로젝트 유형에 따라 구조와 정확한 내용은 다르겠지만, 아래와 같은 구조는 좋은 출발점이다.

• Project Title
  • 프로젝트에 대한 설명과 동기
  • Screenshots (if applicable), with captions
  • 특정한 스타일 가이드를 따르고 있다면 코드 스타일 제시
• Getting Started
  • Prerequisites & Installation,
    모든 pre-requisites를 다운 받는 방법에 대한 sample code를 포함한다.
  • Local Development,
    로컬 개발 환경 설정 및 로컬 환경에서의 프로젝트 실행 방법을 포함한다.
  • 테스트와 테스트를 실행하는 방법
• API Reference
  • API 문서가 많이 길지 않다면 README에 포함될 수 있다.
• Deployment (if applicable)
• Authors
• Acknowledgements(사사, 감사의 말)