FastAPI 서버개발, FastAPI 자동 문서화

FastAPI는 현대적인 웹 애플리케이션을 구축하기 위한 높은 성능을 자랑하는 Python 웹 프레임워크입니다. FastAPI의 가장 큰 장점 중 하나는
자동화된 API 문서화인데, 이는 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 해줍니다. 이 글에서는 FastAPI의 문서화 기능과 그 사용 방법에 대해
자세히 설명하겠습니다.

FastAPI 소개

FastAPI는 Starlette를 기반으로 하여 만들어진 프레임워크로, asyncio를 지원하여 비동기적인 요청 처리가 가능하며, 매우 높은 성능을 자랑합니다.
FastAPI는 데이터 검증, 직렬화, 문서화 등의 기능을 쉽게 구현할 수 있도록 도와줍니다. 또한, FastAPI를 사용하면 Python 타입 힌트를 활용하여 API의 입력 및 출력
모델을 정의하고, 이를 기반으로 자동으로 문서를 생성할 수 있습니다.

FastAPI의 기본적인 사용법

FastAPI를 사용하기 위해서는 먼저 FastAPI 라이브러리를 설치해야 합니다. 아래와 같은 명령어로 설치할 수 있습니다: 

pip install fastapi[all]

FastAPI의 기본적인 사용법을 알아보겠습니다. 아래는 아주 간단한 FastAPI 앱의 예시입니다. 

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

위의 코드에서 FastAPI() 인스턴스를 생성하고, @app.get("/")를 사용하여 루트 경로에 대한 GET 요청을 처리하는
read_root 함수를 정의했습니다. FastAPI는 이 함수를 호출할 때 자동으로 JSON 응답을 반환합니다.

FastAPI의 자동 문서화 기능

FastAPI의 자동 문서화 기능은 기본적으로 Swagger UI와 ReDoc을 제공합니다. FastAPI 앱이 실행되는 동안 다음 URL에서 문서화된 API를 확인할 수 있습니다:

  • Swagger UI: http:///docs
  • ReDoc: http:///redoc

FastAPI는 각 엔드포인트에 대한 문서를 자동으로 생성하며, Swagger UI는 이를 시각적으로 표현합니다.
문서를 구성하는 데 있어서 FastAPI의 장점은 Python 타입 힌트를 이용해 API의 요청 및 응답 모델을 정의할 수 있다는 점입니다.

요청 및 응답 모델 정의

FastAPI에서는 Pydantic을 사용하여 데이터 모델을 정의할 수 있습니다. Pydantic은 데이터 검증과 설정을 위한 데이터 클래스와 검증 기능을 제공합니다.
요청 및 응답 모델을 정의하면 FastAPI는 이를 이용해 자동으로 문서를 생성합니다. 아래는 요청 모델과 응답 모델을 사용하는 예제입니다. 

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

@app.post("/items/", response_model=Item)
def create_item(item: Item):
    return item

위의 코드에서 Item 클래스를 정의하여 요청 모델을 만들었습니다. 이 클래스는 BaseModel을 상속하며
각 필드에 대한 데이터 타입을 정의합니다. @app.post("/items/")를 사용하여 POST 요청을 처리하는
create_item 함수를 정의하고, 이 함수는 요청에서 Item 모델을 인자로 받습니다. 또한, 응답 모델로도 같은
Item 클래스를 사용하고 있습니다.

FastAPI에서의 문서화 항목 설명

FastAPI 자동 문서화에는 몇 가지 유용한 기능이 포함되어 있습니다. 이 섹션에서는 몇 가지 주요 기능에 대해 살펴보겠습니다.

요청 본문 설명

FastAPI는 Pydantic의 모델을 사용하여 API 요청의 본문을 설명합니다. 위의 예제에서는 Item 모델이 요청 본문에 대한
구조를 설명하므로, Swagger UI에서 해당 요청의 구조를 쉽게 이해할 수 있습니다.

쿼리 매개변수 설명

FastAPI는 쿼리 매개변수에 대한 설명도 추가할 수 있습니다. 예를 들어, 아래와 같이 쿼리 매개변수를 사용하는 API를 만들어 보겠습니다. 

@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

위의 코드에서 skip와 limit 매개변수를 정의하였고, 기본값을 설정했습니다. FastAPI는 이 정보에 기반하여
Swagger UI에서 쿼리 매개변수에 대한 설명을 제공합니다.

답변 설명 추가

FastAPI는 응답 타입에 대한 설명도 추가할 수 있습니다. 응답 모델을 정의할 때 response_model 매개변수를 사용하여
명확하게 응답의 구조를 설명할 수 있습니다.

FastAPI 사용자 지정 문서화

기본적으로 FastAPI는 Swagger와 ReDoc을 사용하여 자동 문서화를 제공합니다. 그러나 때때로 사용자 지정 내용을 추가하고 싶을 수 있습니다.
FastAPI는 엔드포인트에 대한 설명 및 태그를 사용자 지정할 수 있는 방법을 제공합니다.

엔드포인트에 대한 설명 추가

FastAPI의 경로에 대한 설명과 설명을 추가할 수 있습니다. 아래는 이를 보여주는 예제입니다. 

@app.get("/items/", tags=["items"], summary="Get items", description="Retrieve a list of items based on skip and limit")
def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

위의 코드에서 tags, summary, 및 description 매개변수를 사용하여 Swagger UI에서
더 나은 설명을 제공합니다. 이는 다른 개발자들이 API를 이해하는 데 큰 도움이 됩니다.

결론

FastAPI는 Python 기반의 API 서버를 쉽고 빠르게 구축할 수 있게 해주는 프레임워크입니다. 자동 문서화 기능을 통해 Swagger UI 및
ReDoc을 제공하여 API의 사용을 훨씬 간편하게 만들어 줍니다. Pydantic을 활용하여 데이터 모델을 정의하고, 이를 기반으로
요청 및 응답을 담당하는 API를 작성할 수 있습니다. 사용자 지정 문서화 기능을 통해 더 나은 API 문서를 작성할 수 있으며, 다른
개발자들과의 협업을 용이하게 할 수 있습니다.

FastAPI의 이러한 특성 덕분에 빠르고 효율적인 백엔드 서버 개발이 가능합니다. 이는 특히 데이터 중심의 애플리케이션을 개발할
때 큰 장점을 제공합니다.