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

 

 

API 문서화(API Documentation)

1. API 문서화 개요

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

API는 서버와 클라이언트 간의 데이터 교환을 원활하게 해주는 매개체 역할을 합니다.
API는 사용자가 요청을 쉽게 전송하고, 요청에 대한 응답을 받을 수 있게 도와줍니다.
API는 현대 소프트웨어 개발에서 필수 요소로 자리 잡았으며, 이를 통해 효율적인 개발 및 유지보수가 가능합니다.

• 예시: API는 식당의 메뉴판과 같아서, 사용자는 주방에서 일어나는 일을 알 필요 없이 메뉴판을 보고 서버에 요청만 보내면 됩니다.
• API는 개발 복잡도를 줄이고, 이미 개발된 API를 재사용할 수 있어 시간과 비용을 절감합니다.

1.2 API 문서(API Documentation)

API 문서는 API 사용법을 개발자에게 알려주는 설명서입니다.
클라우드 서비스 API 등 다양한 서비스는 API 사용 가이드를 제공하여 개발자가 기능을 쉽게 구현하도록 도와줍니다.

API 문서의 필요성

• API가 제공하는 기능과 사용 방법을 명확히 파악 가능
• 요청/응답 형식, 파라미터 설명 등 상세한 정보 제공
• 오류 메시지 및 해결 방법 제시로 문제 해결 지원
• 협업 시 일관성 있는 개발을 통해 생산성 향상

2. 좋은 API 문서의 핵심 요소

2.1 가독성

API 문서는 쉽게 읽히고 이해할 수 있어야 합니다.
제목, 부제목, 리스트, 도표 등을 활용하여 시각적으로 쾌적하게 구성하는 것이 중요합니다.

• 툴 추천: Swagger, Postman, Document360 등의 문서화 도구들은 가독성 높은 문서 작성을 지원합니다.

2.2 목적성

문서 서두에 API의 핵심 기능과 역할을 명확히 제시하여 사용자가 API를 올바르게 이해할 수 있도록 합니다.

• 목적성 없는 문서: 사용자는 혼란을 겪을 수 있습니다.
• 목적성 있는 문서: API의 주요 기능과 용도를 명확하게 파악하여 적절한 상황에 사용할 수 있게 도와줍니다.

2.3 간결성

API 문서는 기술적으로 복잡한 내용을 다루기 때문에, 핵심 내용에 집중하고 불필요한 설명은 줄여야 합니다.
간결한 문서는 정보를 빠르게 찾을 수 있어 효율성을 높여줍니다.

2.4 체계성

문서가 체계적으로 정리되어 있어야 사용자들이 필요한 정보를 쉽게 찾을 수 있습니다.
목차와 섹션을 논리적으로 배열하여 효율적인 문서 탐색이 가능하도록 해야 합니다.

2.5 일관성

API 문서에서 일관된 스타일과 용어 사용은 문서의 신뢰성을 높입니다.
파라미터 명명 규칙이나 응답 데이터 구조의 일관성은 API 사용성을 크게 향상시킵니다.

2.6 사용자 친화적(User-friendly)

기술 용어에 대한 간단한 설명을 추가하여 개발자 및 사용자들이 쉽게 이해할 수 있게 해야 합니다.
모든 기술 수준의 사용자를 고려하여 문서를 작성하는 것이 중요합니다.

2.7 다양한 예시

요청/응답 파라미터, 헤더, 코드 예시를 포함해 API 동작을 구체적으로 설명하고 다양한 활용 예시를 제공해야 합니다.
JSON, XML 형식의 구체적인 예시는 사용자에게 명확한 이해를 돕습니다.

3. API 문서화란?

API 문서화는 클라이언트가 API에 요청을 보내기 위해 필요한 정보를 문서화하는 과정입니다.
API 문서는 개발자 간의 소통을 원활하게 하고, 변경 사항을 쉽게 전달하는 중요한 역할을 합니다.

• 잘 작성된 API 문서는 개발 생산성을 높이고, API 채택률을 증가시키며, 문제 해결을 지원합니다.

4. API 문서화의 주요 구성 요소

4.1 API 개요 및 소개

API가 제공하는 기능과 목적을 간단히 설명합니다.

• 예시: 고객 정보를 조회하는 API는 고객의 기본 정보, 연락처, 구매 내역 등을 확인할 수 있습니다.

4.2 인증 정보

API 호출에 필요한 인증 방법(API 키, OAuth, JWT 등)과 절차를 설명합니다.

• 예시: API 키는 회원 가입 후 발급받을 수 있으며, 요청 시 헤더에 'X-API-Key'로 포함해야 합니다.

4.3 엔드포인트

API 각 기능에 접근하기 위한 URI와 HTTP 메서드(GET, POST, PUT, DELETE)를 명시합니다.

• 예시: GET /customers/{customerId}

4.4 요청 및 응답 형식

요청 시 필요한 파라미터(쿼리, 경로, 헤더, 바디)와 응답 형식을 설명합니다.

• 예시: 요청 파라미터의 필드명, 필수 여부, 기본값, 설명 등을 포함합니다.

 

 

4.5 API 문서의 중요성

• 생산성 향상
  • 명확하고 체계적인 정보를 제공하여 개발자가 필요한 정보를 쉽게 찾아 활용할 수 있게 함
  • 요청과 응답에 대해 검증된 샘플 코드를 제공하여 사용자가 흔히 저지를 수 있는 실수를 사전에 방지할 수 있도록 함
  • 이러한 특징은 API의 올바른 구현과 개발 시간 단축으로 생산성을 향상하는 데 기여함
• API 채택률 증가
  • 잘 작성된 문서는 사용자가 API를 빠르고 쉽게 이해하고 사용할 수 있어 채택률을 높임
  • 이러한 특징은 API의 품질과 신뢰성을 보장하고 마케팅 도구로 활용하는 데 기여함
• 신속한 문제 해결
  • API 사용 시 발생할 수 있는 에러와 처리 방법을 제공하여 문제를 빠르게 해결할 수 있게 함
  • 이러한 특징은 개발 시간을 단축하는 데 기여함
• 일관된 사용 경험 제공
  • 여러 팀이나 프로젝트에서 동일한 API를 규칙과 지침에 따라 일관되게 사용할 수 있게 함
  • 이러한 특징은 코드의 유지 보수 및 확장을 용이하게 하며, 여러 사용자가 협업하는 상황에서의 혼란을 방지하는 데 기여함
• 다양한 지원
  • 제공되는 SDK, 라이브러리, 테스트 환경 등을 활용하여 API 기능을 쉽게 테스트할 수 있도록 지원함
• 보안 강화
  • 인증 정보와 인증 절차를 제공하고 사용 권한을 제한하여 보안위협으로부터 사용자를 보호함
  • 이러한 특징은 API의 사용성과 보안을 강화하는 데 기여함
• API 품질 보장
  • 제공되는 변경 사항, 버전 업데이트 등의 정보를 통해 사용자가 API의 변경 사항을 개발에 적용하고 대처하여 API의 최신 상태를 유지할 수 있도록 함
  • 제한 사항에 따라 API를 효율적으로 사용할 수 있도록 함
  • 이러한 특징은 API의 호환성 문제와 과도한 요청으로 인한 서비스 중단 문제를 방지하는 데 기여함
• 지속적인 개선
  • 잘 작성된 API 가이드로 인해 사용자가 증가하면, 사용자의 커뮤니티를 통해 API를 사용하면서 발생하는 추가적인 문제에 대한 해결 방법과 API의 활용에 대한 새로운 사례를 발견할 수 있음
  • 이러한 특징은 API를 지속적으로 개선하여 사용자 만족도를 증가시키고, 더 많은 사용자가 유입되는 데 기여함

• API 문서화는 단순한 사용 설명서를 넘어, 복잡한 개념을 명확하게 전달하고 다양한 사용 예시를 제공하여 개발자들이 API를 최대한 활용할 수 있도록 돕는 중요한 도구임

5 API 문서화 도구

5.1 Swagger

5.1.1 Swagger 개요

• 스웨거(Swagger)란?
  • Web API 문서화를 위한 도구
  • 스웨거 홈페이지(https://swagger.io)에서는 스웨거를 OAS(Open API Specification)라고 소개
    • API들이 가지는 명세(Spec)을 관리하기 위한 프로젝트
  • Web API를 수동으로 문서화 하는 것은?
    • 굉장히 힘든 작업의 하나
    • Web API의 스펙이 변경되었을 때 문서 역시 변경이 되야 하는데 이를 유지하는 것이 쉽지 않음
    • Swagger를 사용하면 문서가 자동으로 갱신이 되기 때문에 Web API가 수정되더라도 상관 없음
      
      
• 스웨거의 기능(스웨거 홈페이지에 의하면)
  • API Design
  • API Development
  • API Documentation
  • API Testing
  • API Mocking and Virtualization
  • API Governance
  • API Monitoring
  • OpenAPI & Swagger
    
    
• 스웨거의 존재의의
  • Web API를 만드는 개발자와 Web API를 이용하는 개발자가 있다고 생각해 보자.
  • Web API를 이용하는 개발자는 Web API가 만들어질 때까지 기다린다면 작업이 상당히 느려질 수 있다.
  • Web API를 만드는 사람과 Web API를 사용하는 사람 간에 미리 명세를 정의하고 공유할 수 있다면 개발이 상당히 편리해 질 것이다.
  • 이를 가능하게 도구 중 하나가 Swagger 이다.

---

• 장점
  • 아름다운 UI
  • API 테스트 기능 제공
• 단점
  • 문서의 신뢰도를 높게 유지하기 어려움

 

<참고 출처>

• https://backstreet-programmer.tistory.com/174
• https://backstreet-programmer.tistory.com/175

Django - Swagger 연동하기 2편 - swagger parameter schema

 

실습을통해 진행한 결과 아래와 같이 나옴

 

5.2 Spring REST Docs

5.2.1 Spring REST Docs 개요

 

• Spring REST Docs란?
  • REST API에 대한 정보를 제공하는 Docs를 생성할 수 있는 Spring 진영에서 제공하는 툴
  • Spring MVC Test 코드 작성시 추가적으로 Docs를 생성하는 코드를 첨가하여 생성할 수 있음
  • REST Docs는 REST 아키텍처의 self-descriptive 규약을 지키기 위해 REST API의 리소스 및 API 명세 그리고 요청과 응답 데이터의 설명까지 포함된 문서를 만들 수 있게 해줌

 

 

• 장점
  • 테스트를 통과해야만 문서가 작성되므로 신뢰도가 높음
• 단점
  • 문서가 Swagger에 비해 아름답지 않음
  • API 테스트 기능을 지원하지 않음
  • 주로 Java와 Spring Framework에서 사용됨(기본적으로 파이썬을 지원하지 않음)

5.3 OpenAPI Specification (OAS)

• RESTful API를 쉽게 관리하고 사용할 수 있도록 도와주는, RESTful API 스펙에 대한 사실상의 표준 명세 작성 방식
• API의 구조와 작동 방식을 명확하게 문서화할 때 사용할 수 있음
• 보통 JSON이나 YAML 형식으로 작성됨
• API를 사용하기 위한 인증 방법, 엔드포인트와 요청 및 반환 데이터 등이 명세에 포함되어 있어서 코드나 문서 없이도 전체 구조를 이해하기 쉬움
• 자동으로 문서가 생성되기 때문에 개발 과정 중 문서화에 소요되는 시간을 줄일 수 있으며, 명확한 커뮤니케이션을 도와줌
• Swagger와 Spring REST Docs의 장점을 결합할 수 있음
• 다양한 API 클라이언트에서 지원함
• 여러 API 개발 도구와 호환되어 API 테스팅, 모니터링, 버전 관리 등에도 사용될 수 있음

6. 파이썬 API 문서화

6.1 Doc String

6.1.1 Doc String 개요

• Doc String은 파이썬 코드에서 함수, 클래스, 메소드 등의 설명을 추가하는 메타데이터로, 코드 문서화 및 유지보수에 큰 도움을 준다.
• 파이썬 인터프리터는 이를 일반 주석과 구분하며, 코드의 기능과 사용법을 설명하는 역할을 한다.

6.1.2 Doc String의 중요성

• 코드 문서화: 각 개체의 역할과 사용법을 명확하게 문서화해, 다른 개발자들이 코드를 이해하고 사용할 때 큰 도움이 된다.
• 자동 문서 생성: Doc String을 사용하면 Sphinx와 같은 도구를 통해 프로젝트의 API 문서를 자동으로 생성할 수 있다.
• IDE와의 통합: 일부 IDE에서는 Doc String을 바탕으로 자동완성 기능과 코드 설명을 제공하여 개발 효율성을 높여준다.

6.1.3 Doc String 작성 방법

• 함수, 클래스, 메소드 정의 바로 다음 줄에 쌍따옴표(""")나 홑따옴표(''')로 Doc String을 작성한다.
• 주요 작성 규칙:
  • 개체의 역할과 목적을 간결하게 설명.
  • 매개변수와 반환값 설명.
  • 사용 예시나 예제 코드를 포함.

6.1.4 Doc String의 단점

• 코드가 변경되면 문서를 수동으로 업데이트해야 한다.
• 유용한 문서화를 위해서는 상세한 설명이 필요하며, 다소 시간이 걸릴 수 있다.

6.1.5 적절한 문서 유지의 필요성

• 문서화는 필수적인 작업이며, 지속적인 업데이트와 관리가 필요하다.
• 모든 팀원이 문서화에 노력해야 하며, 이를 통해 더 나은 협업과 유지보수가 가능하다.

6.2 Sphinx

6.2.1 Sphinx 개요

• Sphinx는 파이썬 생태계에서 널리 사용되는 문서 생성 도구로, 코드에 작성된 Doc String을 기반으로 다양한 형식의 문서를 자동으로 생성할 수 있다.
• HTML, PDF, EPUB 등 다양한 형식으로 프로젝트 문서를 만들 수 있어 개발자 및 사용자들이 프로젝트를 이해하는 데 큰 도움을 준다.

6.2.2 Sphinx의 중요성

• 포괄적인 문서화: 함수, 클래스, 모듈, 패키지 등 모든 코드 개체에 대한 문서를 자동 생성.
• 자동 업데이트: 코드 변경 시 Sphinx가 문서를 자동으로 업데이트하여 최신 상태를 유지.
• 다양한 형식으로의 출력: HTML, PDF, EPUB 등 여러 형식으로 문서를 제공.
• 협업과 공유: 버전 관리 시스템과 통합해 협업을 간편하게 하고, 다른 개발자와 문서를 공유할 수 있다.

 

Sphinx는 아직 사용까지는 해보지 못해서 다음 시간에 사용해 볼 예정이다.

 

 

• 오늘의 오류 <오류>
  - 초반에 python manage.py runserver 하려고 했는데 ModuleNotFoundError: No module named 'pkg_resources' 오류가 발생하였다.
  - 에러 메시지를 보면 pkg_resources 모듈을 찾을 수 없다는 오류였고, 검색 결과 이 모듈이 setuptools 패키지 내에 포함되어있다는 것을 알게 되었다.
  - 확인 결과 setuptools 가 설치되지 않았거나 손상된 경우 발생하는 문제라고 해서, 이를 해결하고자 패키지를 다시 설치하거나 업데이트 하는것 중에서 업데이트를 하는 방법을 택했었다.
  - ''' pip install --upgrade setuptools '''
  
  - 두번째로 Sphinx 를 실습하는 도중에 sudo apt install tree 이 커멘드가 윈도우에서 먹히지 않는것을 확인했다.
  - 윈도우에서는 tree 명령어를 사용하려면 tree 유틸리티를 설치해야하고, apt 명령어 대신 다른 방법을 사용해야한다는 것을 알게되었다.
  - winget 패키지 관리자를 사용하는 방법과 Git Bash, WSL(Windows Subsystem for Linux)를 이용하는 방법이 존재한다고 한다.
  - 저는 여기서 winget install GNU.tree 명령어를 이용해서 tree를 이용할 수 있게 해봤다.(아직 뒷부분은 시도해보지 않아서 제대로 동작하는지는 확인하지는 못했다)

 

- 오늘의 회고

https://github.com/Python-Backend-Team3/Team-TIL/blob/main/9.19%20~%209.30%20%ED%9A%8C%EA%B3%A0/2024-09-20%20-%20%EC%A7%80%EC%9B%85.md

Team-TIL/9.19 ~ 9.30 회고/2024-09-20 - 지웅.md at main · Python-Backend-Team3/Team-TIL