[파이썬] FastAPI 기초

시작에 앞서

해당 내용은 <가장 빠른 풀스택을 위한 Flask & FastAPI>, Dave Lee 지음. BJ Public 출판.
내용을 토대로 작성되었습니다. 보다 자세한 사항은 해당 교재를 참고하시기 바랍니다.

---

Hello, World! API 만들기

 

시작하기 전에, 먼저 main.py 파일을 만들고 터미널에서 FastAPI 라이브러리를 설치한다.

pip install fastapi==0.104.1

 

그리고나서, main.py에 해당 코드를 작성한다.

# main.py
from fastapi import FastAPI #FastAPI 라이브러리 import

app = FastAPI() # FastAPI 인스턴스 생성

@app.get("/") # HTTP GET 요청을 "/" 경로로 받을 준비
def read_root(): # 해당 요청을 처리할 함수 정의
    return {"message": "Hello, World!"} #JSON 형태의 응답 반환

 

[각 코드별 설명]

• from fastapi import FastAPI: FastAPI 클래스를 가져온다.
• app = FastAPI(): FastAPI 인스턴스를 생성한다
• @app.get("/"): 데코레이터를 사용해 HTTP GET 요청을 어떤 함수가 처리할지 지정한다. (여기서는 "/" 경로에 대한 GET 요청을 처리)
• def read root(): GET 요청을 처리할 함수 (이름은 임의 지정 가능)
• return ["message": "Hello, World!"}: 함수에서는 JSON 형태의 응답을 반환. FastAPI가 자동으로 이를 JSON 형식으로 반환

---

서버 실행

 

FastAPI 애플리케이션을 로컬에서 실행하고 싶다면, Uvicorn 이라는 ASGI 서버 구현체가 필요하다.

★ Uvicorn: 비동기 웹 서버로, FastAPI 의 비동기 처리 기능과 호환되어 효율적인 성능을 발휘한다.

 

◆ Uvicorn 설치하기

pip install uvicorn==0.27.0.post1

 

설치가 완료되었다면 FastAPI 애플리케이션을 실행하는 단계로 넘어갈 수 있다.

그리고 터미널에 다음과 같이 입력한다.

uvicorn main:app --reload

 

[설명]

• main: FastAPI 애플리케이션 코드가 작성된 파이썬 파일의 이름을 의미. (main.py 파일 내에 있다고 가정)
• app: FastAPI 인스턴스를 생성하는 객체의 변수 이름을 지칭. (app = FastAPI() 라고 정의된 경우)
• --reload: 개발 중에 코드를 수정할 때마다 서버가 자동으로 재시작하도록 설정. 코드 변경 사항이 바로 적용되도록 해서 개발 과정을 더 빠르고 효율적으로 만들어줌.

명령어를 실행하고 나면, FastAPI 애플리케이션은 기본적으로 http://127.0.0.1:8000 주소에서 서비스 된다.

FastAPI 에는 Uvicorn 외에 다른 ASGI 지원 프레임워크에서도 사용할 수 있지만, FastAPI 는 Uvicorn의 비동기 처리 기능을 최대한 활용하여 뛰어난 성능을 제공하므로 FastAPI+Uvicorn 조합이 가장 권장된다.

 

★ 플라스크의 경우, 애플리케이션을 실행할 경우에는 'flask run' 명령어를 사용하며, 디폴트로 app.py 파일을 실행.

▶ FastAPI와 플라스크 모두 터미널을 통해 실행할 수 있지만, 사용하는 명령어와 실행되는 서버의 종류가 다르다.

• FastAPI: 비동기 처리를 위해 Uvicorn 사용 (표준)
• 플라스크: 자체적인 서버를 사용하거나 Gunicorn 등의 동기 처리 기반 프로그램 사용

---

자동 문서화

 

FastAPI에서는 자동 문서화를 통해 개발 중에 자주 마주치는 문제 중 하나인 '문서화의 부재'를 해결할 수 있다.

★ 문서화의 부재: 개발자가 API를 개발하고 나면, 그다음 단계는 일반적으로 API가 어떻게 동작하는지를 문서화하는 것이다. 그러나 이 과정은 시간이 많이 들고, 자주 업데이트 해야 하는 문제가 있다.

 

▶ FastAPI를 사용하면 코드에 작성한 타입 힌트와 함께 추가적인 데코레이터나 매개변수를 통해 API 에 대한 문서를 자동으로 생성한다. 자동문서화는 FastAPI를 사용하는 데 있어 큰 장점 중 하나이며, 이를 활용하면 개발 과정이 더욱 효율적이고 간편해진다.

 

해당 개념에 대한 좀 더 자세한 사항은 하단 링크 확인

https://puppy-foot-it.tistory.com/358

[API] 자동 문서화 (feat. 문서화의 부재)

---

◆ FastAPI 애플리케이션에서 지원하는 두 가지 형태의 자동 문서화

 

1. Swagger UI (Docs)

 

FastAPI 애플리케이션을 실행한 상태에서 http://127.0.0.1:8000/docs를 입력하면, Swagger UI(스웨거 UI)라는 문서화 툴을 볼 수 있다. 여기서는 각 API 엔드포인트의 상세 정보를 볼 수 있고, 실제로 API를 테스트해 볼 수도 있다.

• Endpoint List: 화면 좌측에는 사용 가능한 모든 API 엔드포인트가 나열된다.
• Test Button: 각 엔드포인트 옆에 있는 <Try it out> 버튼을 클릭하면 해당 API를 직접 테스트할 수 있다.
• Parameters Input: API 호출에 필요한 매개변수를 입력하는 부분이다.
• Execute: 매개변수를 입력한 뒤, 이 버튼을 클릭해 API를 호출한다.
• Response: API 호출의 결과가 이곳에 표시된다.

처음 화면에서 위와 같은 정보가 보이지 않는다면, [GET] 메뉴 오른쪽 끝에 있는 아래 화살표를 클릭하여 폴딩 화면을 펼친 후, <Try it out> 버튼을 누르고, <Execute> 버튼을 누르면 된다.

 

[Swagger UI 특징]

• 대화형 API 테스트 가능: Swagger UI는 API 엔드포인트를 실제로 호출하여 테스트할 수 있다.
• 매개변수 형태 및 예시 표시: 요청 바디, 경로 매개변수, 쿼리 매개변수 등을 자세히 설명하며, 예시 값을 제공한다.
• OAuth2 지원: OAuth2 를 사용한 인증을 직접 태스트 할 수 있다.
• 커스터마이징 가능: 플러그인이나 추가 설정으로 UI를 변경할 수 있다.

---

2. 리독(ReDoc)

 

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

• Side Menu: 화면 좌측의 사이드 메뉴에서 API의 전반적인 구조를 확인할 수 있다.
• Endpoint Description: 각 엔드포인트의 상세한 설명과 요청/응답 예시가 제공된다.
• Models: 사용되는 데이터 모델의 구조와 설명이 나와 있다.

[리독의 특징]

• 더 깔금한 UI: 리독은 상대적으로 더 깔끔하고 직관적인 UI를 제공한다.
• 마크다운 지원: API 설명을 위해 마크다운 문법을 지원한다.
• 단일 페이지 구조: 모든 정보를 하나의 페이지에서 볼 수 있어, 문서의 전체 구조를 한 눈에 파악하기 쉽다.
• 대화형 테스트 불가능: 리독은 대화형 API 테스트를 지원하지 않는다.

---

자동 문서화의 주요 용어
("Hello, World!" 예제 기반)

 

http://127.0.0.1:8000/docs 에서 <Try it out> 버튼과 <Execute> 버튼 클릭

 

- curl

• 배경지식: curl은 터미널(명령 프롬프트)에서 사용할 수 있는 명령줄 도구로, 웹사이트나 API 서버와 통신할 수 있게 해준다.
• 이미지에서의 의미: curl 명령어는 해당 API를 호출하는 방법을 나타내며, 이경우엔 GET 요청을 http://127.0.0.1:8000/ 주소로 보내라는 명령이다.

- GET / Read Root

• 배경지식: HTTP 요청은 여러 종류가 있는데 GET은 갖아 기본적인 유형으로, 서버로부터 정보를 조회하는 데 사용된다.
• 이미지에서의 의미: /경로 (루트 경로)로 GET 요청을 보낼 때의 문서화이다.

- 200

• 배경지식: HTTP 응답 코드는 서버가 클라이언트의 요청에 어떻게 응답했는지를 나타내는 숫자 코드이며, 200 코드는 요청이 성공적으로 완료되었음을 의미한다.
• 이미지에서의 의미: 이 API 엔드포인트를 호출했을 때 성공적인 응답을 받으면, 서버는 200 응답 코드와 함께 데이터를 반환한다.

- application/json

• 배경지식: application/json은 MIME 타입의 하나로, 데이터가 JSON 형식으로 반환되었음을 나타낸다. MIME 타입은 데이터의 종류를 나타내는 문자열이다.
• 이미지에서의 의미: 이 API 엔드포인트에서 반환되는 응답 데이터는 JSON 형식임을 나타낸다.

- Response body

• 배경지식: 서버의 응답에는 헤더와 바디(body)가 포함된다. 바디는 서버가 반환하는 실제 데이터를 포함한다.
• 이미지에서의 의미: {"message": "Hello, World!"}는 서버가 반환되는 실제 데이터이다. 이 경우, 메시지로 "Hello, World!" 를 반환한다.

- Response headers

• 배경지식: 응답 헤더는 서버의 응답에 대한 메타데이터 (정보의 정보)를 포함하고 있다.
• 이미지에서의 의미: content-length, content-type 등의 헤더 정보를 볼 수 있다. 이는 반환된 데이터의 길이, 데이터 타입 등의 정보를 나타낸다.