#파이썬 24.09.20_Django 기반의 테스트 주도 개발 방법론(TDD)&API 문서화

API 문서화(API Documentation)

1. API 문서화 개요

 

1.1 API(Application Programming Interface, 응용 프로그램 인터페이스)

• API는 서버와 클라이언트(사용자)의 중간에서 원활하게 데이터를 주고받을 수 있게끔 매개체의 역할을 수행
  • 사용자가 무엇을 요청할 수 있는지 알려주고, 그 요청이 제대로 전달되었는지 확인하고, 응답까지 전달
• API는 쉽게 비유하자면 식당의 메뉴판과 같음
  • 클라이언트인 사용자는 주방에서 어떤 일이 일어나는지 자세히 알 필요 없이 메뉴판에 적힌 메뉴를 선택하고 서버에게 요청을 보내기만 하면 됨
• 현대 소프트웨어 개발 환경에서 API는 필수적인 요소로 자리 매김
  • API를 통해 더욱 빠르고 효율적인 개발이 가능
  • 각 기능을 독립적으로 분리하여 개발의 복잡도를 줄이고 유지보수를 용이하게 함
  • 이미 개발된 API를 다양한 애플리케이션에 재사용할 수 있어 시간과 비용을 절감할 수 있음

 

1.2 API 문서(API Documents)

• API 문서
  • 특정 서비스의 API를 이용하는 개발자를 위한 사용 설명서
  • 다양한 API들을 한 곳에 모아두고 사용 방법 및 환경 등 기본적인 정보를 제공gka
  • 예시
    • 클라우드 플랫폼에서는 클라우드 서비스를 원활하게 이용할 수 있도록 사용 가이드와 API 가이드를 함께 제공함
    • 개발자들, 즉 고객들은 원하는 기능을 소프트웨어에 구현하기 위해 이를 참고하여 개발함

 

• API 문서의 필요성
  • API가 제공하는 다양한 기능과 각 기능의 역할을 정확하게 파악하여 이를 응용할 수 있음
  • API의 호출 방법, 데이터 형식, 요청(Request) 시 필요한 파라미터와 그 역할, 응답(Response) 결과 등을 상세하게 설명하고, 예시 코드를 통해 실제 사용 방법을 보여주어 개발자와 사용자의 이해를 도와줌
  • 오류 코드 및 메시지 등을 통해 API 사용 중 발생 가능한 오류에 대한 정보를 제공하고, 문제를 빠르게 진단할 수 있도록 도와줌
  • 해결 방법을 제공하는 경우도 있음
  • 이 외에도 여러 개발자가 협업 시 동일한 API 문서를 참고함으로써 개발 과정과 결과의 일관성을 확보할 수 있어 개발 생산성을 향상시킬 수 있음

• 좋은 API 문서의 핵심 요소
  • 좋은 API 문서는 단순한 사용 설명서를 넘어, 복잡한 개념을 명확하게 전달하고 다양한 사용 예시를 제공하여 개발자들이 API를 최대한 활용할 수 있도록 도와야 함
    
    
  • 가독성
    • 기술적인 문서일수록 복잡하고 전문적인 용어가 많아지기 쉬워 자칫 어렵고 이해하기 힘듦
    • 따라서 API 문서를 작성할 때에는 독자, 즉 개발자와 사용자가 쉽게 읽고 이해할 수 있도록 해야 함
      • 문서 내의 제목, 부제목, 리스트 등을 활용해 시각적으로 쾌적하게 구성
      • 도표나 플로우 차트 등을 활용
    • 가독성이 좋은 문서는 API 문서의 접근성을 높이고, 사용자의 만족도를 향상시킬 수 있음
      • Swagger, Postman, Document360 등 다양한 API 문서 작성 툴에는 기본적인 불렛팅(bulleting, 하위 문서 목록화) 세팅이 되어 있으니, 이를 활용하는 것도 좋음
        
        
  • 목적성
    • 문서의 서두에서 API의 핵심을 명확하게 제시하여 목적성을 드러내야 함
      • 사용자가 문서를 처음 접했을 때 해당 API의 역할 및 기능을 직관적으로 이해할 수 있어야 함
      • API의 기능과 사용 목적을 도입문 등 서두에 두괄식으로 배치하는 방법이 가장 효과적
    • API가 어떤 문제를 해결할 수 있는지, 어떤 상황에서 사용될 수 있는지 바로 파악할 수 있도록 돕는 것이 중요함
      • 이는 사용자가 API의 적절한 사용 상황을 쉽게 떠올릴 수 있게 해줌
      • 사용자가 해결하고자 하는 문제에 API를 활용할 수 있는지 판단하는 데 도움을 줌
    • 목적성이 명확하지 않은 문서
      • 사용자에게 혼란을 줄 수 있음
      • API의 주요 기능과 용도를 달리 이해하는 상황을 초래할 수 있음
    • 목적성이 명확한 문서
      • API의 각 기능이 전체 시스템 내에서 어떻게 연결되고, 어떤 역할을 수행하는지 이해하는 데 큰 도움이 됨
        
        
  • 간결성
    • API 문서는 복잡한 기술에 대한 세부 사항을 포함하고 있기 때문에, 간결하게 적는 것이 좋음
      • 일반적으로 개발자 및 사용자는 API 문서에 장대한 설명을 기대하지 않음
      • 여러 가지 기능, 메서드, 데이터 구조 등 필요한 부분만 골라서 읽으려는 경향이 강함
    • 길고 복잡한 문서
      • 원하는 정보를 찾는 데 많은 시간이 소요됨
      • 전체 내용을 파악하는 데 어려움을 겪을 수 있음
    • 간결한 문서
      • 핵심적인 내용에 집중하여 불필요한 설명을 최소화
      • 불필요한 세부 사항이나 중복된 설명을 배제하여 문서의 효율성을 높임
      • 문서 탐색에 시간을 덜 소모함 → 실제 개발 작업에 더 많은 시간을 할애 → 효율성 향상
    • 간결성은 단시간 내에 빠르게 API를 이해하고 적용해야 하는 개발자들이 협업하는 상황에서 매우 중요함
      
      
  • 체계성
    • API 문서는 체계적으로 정리될수록 완성도가 높아짐
    • 체계적 구성
      • 문서의 구조가 명확하게 일관되게 정리되어 있어야 한다는 것을 의미
      • 사용자가 필요로 하는 정보를 쉽게 찾을 수 있도록 목차를 설계하고, 엔드포인트, 요청 및 응답 형식, 오류 코드 등의 정보를 각 섹션을 논리적으로 배열해야 함
      • 사용자가 필요한 정보를 빠르게 찾고, 효율적인 개발 환경을 조성하는 데 도움이 됨
      • API의 변경 사항이나 업데이트 관리에도 유리
      • 새로운 기능의 추가나 수정 시에도 문서의 일관성 유지가 용이
        • 개발자와 사용자는 항상 최신 정보를 확인할 수 있음
        • API를 효과적으로 활용하는 데 필요한 시간 절약
    • API 문서의 체계성은 사용자 경험을 향상시키며, 개발자들이 더욱 생산적으로 작업할 수 있는 기반을 제공함
      
      
  • 일관성
    • 좋은 API 문서의 핵심 요소의 하나
    • 일관된 스타일과 용어의 사용
      • 문서에 통일감을 줌
      • 동시에 작성자의 전문성을 높임
      • 더 빠르고 효율적인 활용이 가능하게 함
      • 예시
        • 파라미터의 명명 규칙이 일관되지 않거나 응답 데이터의 구조가 실제 예시와 다르게 제공된다면
          • API 문서를 사용하는 데 어려움을 겪을 수 있음
        • 모든 파라미터에 대한 설명이 일관되게 작성되면
          • 개발자는 특정 기능을 찾기 위한 시간을 줄일 수 있으며
          • API의 전반적인 구조를 상대적으로 빠르게 파악할 수 있음
        • 오류 메시지나 상태 코드의 설명 역시 일관성을 유지한다면
          • 오류 원인을 좀 더 수월하게 해결할 수 있음
    • 일관된 문서
      • 신뢰성을 높이며
      • 개발자와 사용자의 API 사용성을 향상시킴
        
        
  • 사용자 친화적(User-friendly) 관점
    • 문서 작성 시 사용자의 필요를 최우선을 고려해야 함
      • 사용자 친화적인 관점을 고려해야 함
      • 기술 용어에 대한 간단한 설명 추가 및 쉬운 용어로 대체하여 개발자와 사용자가 내용을 쉽게 이해하도록 해야 함
        • API 문서를 읽는 사용자는 다양한 기술 수준을 가지고 있다는 사실
      • 주니어 개발자와 시니어 개발자, 그리고 일반 사용자가 모두 이해할 수 있는 보편적인 언어와 설명 방식을 사용하며 접근성을 높일 수 있음
      • 개발자와 사용자가 작업 중 해당 문서를 참고하게 되는 시점을 파악하여 문서를 작성하는 것도 좋음
        • 사용자가 문서를 API 초기 설정 시 읽게 되는지, 혹은 오류가 발생했을 때 읽게 되는지 등 다양한 상황을 고려한다면 더욱 사용자가 읽기 쉬운 API 문서를 작성할 수 있음
          
          
  • 다양한 예시
    • 다양한 사용 예시를 포함하는 것 역시 좋은 API 문서 작성을 위해서 필요함
      • 요청/응답 파라미터, 헤더, 예시 코드 등을 통해 API의 동작 원리와 사용 방법을 더 잘 이해할 수 있도록 함
      • API의 활용 가능성을 넓힐 수 있음
    • JSON, XML 등 형식의 구체적인 예시 코드는 단순한 설명만으로는 이해하기 어려운 부분을 명확하게 전달할 수 있음
    • 개발자 및 사용자는 예시를 통해 API가 실제로 적용되는 상황을 직접 확인할 수 있음
    • Java, Python 등 프로그래밍 언어로 작성된 실행 가능한 코드 스니펫 형태의 예시 코드는 사용자가 몇 가지 간단한 값만 입력한다면 바로 테스트해 볼 수 있어 API의 활용도를 높이고, 사용자가 겪을 수 있는 혼란을 줄일 수 있음

 

1.1 API 문서화란?

• 클라이언트가 REST API 애플리케이션에 요청을 전송하기 위해 필요한 정보를 정리하여 문서화하는 과정
• API 문서화는 개발자가 API를 쉽게 이해하고 올바르게 사용할 수 있도록 돕는 중요한 과정
• API 문서화를 통해 개발자 간의 소통을 원활하게 하고, API의 변경 사항을 쉽게 전달할 수 있음
• 문서화 과정은 API의 품질을 결정짓는 중요한 요소이기 때문에 개발 프로젝트의 성공에 있어 필수적인 요소임
  
  
• 잘 작성된 API 문서
  • 개발 생산성을 높이고
  • API의 채택률을 증가시키며
  • 신속한 문제 해결을 지원함

 

1.2 API 문서화의 주요 구성 요소

 

1. API 개요 및 소개
   • API의 기능과 목적을 간단히 설명함
   • 예시
     • 고객 정보를 조회하는 API: 고객의 기본 정보, 연락처, 구매 내역 등을 확인할 수 있음

1. 인증 정보
   • API 호출 시 필요한 인증 방법(API 키, OAuth, JWT 등)과 절차를 설명함
   • 예시
     • API 키 -회원 가입 후 마이페이지에서 발급받을 수 있음
       • 헤더에 'X-API-Key' 항목으로 모든 요청에 포함되어야 함

1. 엔드포인트
   • API의 각 기능에 접근하기 위한 URI와 엔드포인트의 HTTP 메서드(GET, POST, PUT, DELETE 등)를 명시함
   • 예시

GET /customers/{customerId}

1. 요청 및 응답 형식
   • 요청 시 필요한 파라미터(쿼리, 경로, 헤더, 바디)와 API 응답 구조를 설명함
   • 예시
     • 요청 파라미터의 종류, 필드명, 필수 여부, 기본값, 설명 등을 포함함