FastAPI - Study 2일차 (문서자동화)

FastAPI의 대표적 기능 중 하나는 바로 자동 문서화이다.

 

앞선 1일차에서 Hello, World!! 예제를 했었는데 그때 @app.get("/") 이라는 라우터를 정의했다.

FastAPI는 이 정보를 바탕으로 해당 API 엔드포인트(endpoint)에 대한 문서를 자동으로 생성한다.

 

문서 자동화의 장점은 다음과 같다.

 

● 시간 절약

 - 수동 문서를 업데이트 안해도 되서, 개발에 더 많은 시간을 쏟을 수 있다.

● 최신 정보 유지 

 - 코드가 업데이트되면 문서도 자동 업데이트가 된다.

● API 테스트

 - Swagger UI 또는 리독에서 직접 API를 호출하여 테스트가 가능하다. 이는 특히 프론트엔드 개발자나 다른 백엔드 개발자와 협업시 대단히 유용하다.

● 타입 검사 및 유효성 검증

 - 문서 생성 시 FastAPI는 코드에 명시된 타입 힌트와 유효성 검사 규칙을 참고하여 문서에 반영한다.

   이로 인해 API를 사용하는 개발자의 실수를 줄일 수 있다.

 

 

FastAPI 애플리케이션을 실행한 상테에서 웹 브라우저 주소창에 http://127.0.0.1:8000/docs를 입력하면, Swagger UI(스웨거 UI)라는 문서화 툴을 볼 수 있다.

여기서는 각 API 엔드포인트의 상세 정보 및 실제 테스트가 가능하다.

 

 

 

또한 http://127.0.0.1:8000/redoc 주소로 접속하면 리독(ReDoc)을 이용한 다른 형태의 문서를 볼 수 있다.

 

 

 

1. 스웨거(Swagger) UI(Docs)

FastAPI에서는 주로 두가지 형태의 문서 자동화를 지원한다. 스웨거와 리독 이 두가지 문서화 툴은 몇 가지 차이점이 있다.

 

● 대화형 API 테스트 가능
 - Swagger UI는 API 엔드포인트를 실제로 호출하여 테스트를 할 수 있다.

 

● 매개변수 형태 및 예시 표시

 - 요청 바디, 경로 매개변수, 쿼리 매개변수 등을 자세히 설명하며, 예시 값을 제공한다.

 

● OAuth2 지원

 - OAuth2를 사용한 인증을 직접 테스트할 수 있다.

 

● 커스터마이징 가능

 - 플러그인이나 추가 설정으로 UI를 변경할 수 있다.

 

 

 

2. 리독(Redoc)

 

●  깔끔한 UI

● 마크다운 지원

● 단일 페이지 구조

  - 모든 정보를 하나의 페이지에서 볼 수 있어, 문서 전체 구조를 한눈에 파악하기 쉽다.

● 대화형 테스트 불가능
  - 리독은 스웨거 처럼 대화형 API 테스트 지원이 안된다.

 

---

 

[주요 용어]

1) curl

- 터미널(명령 프롬프트)에서 사용할 수 있는 명령줄 도구로, 웹사이트나 API 서버와 통신할 수 있게 해준다.

curl -X 'GET' \
  'http://127.0.0.1:8000/' \
  -H 'accept: application/json'

 

 

2) GET / Read Root

 - HTTP 요청은 여러 종류가 있는데 GET은 가장 기본적인 유형으로, 서버로부터의 정보를 조회하는 데 사용된다.

 

 

3) 200

 - HTTP 응답 코드는 서버가 클라이언트의 요청에 어떻게 응답했는지를 나타내는 숫자 코드이다. 여기서 200은 요청이 성공적으로 완료되었다는 뜻이다.

 

 

4) application/json

 - aplication/json은 MIME 타입의 하나로서, 테이터가 JSON 형식으로 반환되었다는 것을 나타낸다.

   MIME 타입은 데이터 종류를 나타내는 문자열이다.

 

 

5) Response body

 - 서버의 응답에는 헤더와 바디가 있는데 바디는 서버가 반환하는 실 데이터이다.

 

 

6) Response headers

 - 응답 헤더는 서버 응답에 대한 메타데이터(정보의 정보)를 포함한다.

   Content-length, content-type 등이 이에 해당된다.