현대의 웹 애플리케이션 개발에서는 API와 그 문서화가 매우 중요합니다. FastAPI는
파이썬으로 제작된 웹 프레임워크로, 높은 성능과 사용의 용이성 덕분에 많은 개발자들 사이에서 각광받고 있습니다.
본 글에서는 FastAPI의 자동 문서화 기능에 대해 다룰 것입니다. 특히, Swagger UI와 ReDoc을 사용하여
FastAPI 애플리케이션의 API 문서화를 어떻게 수행하는지에 대해 자세히 알아보겠습니다.
1. FastAPI 소개
FastAPI는 Starlette와 Pydantic을 기반으로 구축된 현대적인 웹 프레임워크로,
RESTful API를 빠르고 쉽게 개발할 수 있도록 설계되었습니다. FastAPI의 주요 특징으로는
매우 빠른 성능, 자동적인 데이터 검증 및 직렬화, 그리고 멀티스레드를 지원하는 비동기 기능 등이 있습니다.
1.1 FastAPI의 특징
- 성능: Starlette를 기반으로 하여 비동기 처리를 통해 높은 성능을 자랑합니다.
- 자동 문서화: Swagger UI와 ReDoc을 통해 API 문서화를 자동으로 수행합니다.
- 유효성 검사: Pydantic을 사용하여 데이터 검증을 쉽게 처리할 수 있습니다.
- 간편한 라우팅 및 경로 매핑: 직관적인 경로 매핑 기능을 제공합니다.
2. FastAPI의 설치
FastAPI를 설치하기 위해서는 먼저 Python이 설치되어 있어야 합니다. 이후 다음의 명령어로 FastAPI와
Uvicorn(ASGI 서버)을 설치할 수 있습니다.
pip install fastapi uvicorn3. FastAPI 애플리케이션 기본 설정
FastAPI로 애플리케이션을 생성하고 기본적인 API를 설정하는 방법을 알아보겠습니다.
아래는 기본적인 FastAPI 애플리케이션의 예제 코드입니다.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
위 코드는 기본적인 FastAPI 애플리케이션을 생성하며, 루트 경로(‘/’)와
파라미터가 있는 경로(‘/items/{item_id}’)를 정의하고 있습니다.
이를 실행하기 위해서는 다음과 같은 명령어를 사용할 수 있습니다.
uvicorn main:app --reload
위의 명령어에서 ‘main’은 파일 이름이며, ‘app’은 FastAPI 인스턴스입니다.
–reload 옵션을 통해 코드 변경 시 서버를 자동으로 재시작하도록 설정할 수 있습니다.
4. FastAPI의 자동 문서화 기능
FastAPI는 Swagger UI와 ReDoc을 사용하여 API 문서화를 자동으로 수행합니다.
이러한 기능은 개발자가 API Endpoint를 정의할 때, FastAPI가 자동으로
해당 API에 대한 문서를 생성하도록 합니다.
4.1 Swagger UI
FastAPI에서 Swagger UI를 사용하는 것은 매우 간단합니다.
애플리케이션을 실행하면 기본적으로 ‘/docs’ 경로에서 Swagger UI에 접근할 수 있습니다.
Swagger UI는 API의 요청 방식(HTTP 메서드, URL 등), 요청/응답의 데이터 구조,
예제 등을 포함하여 직관적으로 API를 테스트할 수 있는 인터페이스를 제공합니다.
Swagger UI 예제
FastAPI 애플리케이션을 실행한 후, 웹 브라우저에서 ‘http://localhost:8000/docs’를
열어보세요. 귀하의 API Endpoint에 대한 문서가 자동으로 생성된 것을 확인할 수 있습니다.
예를 들어 위에서 설정한 루트 경로(‘/’)와 ‘/items/{item_id}’ 경로가
Swagger UI에서 나열되고, 각 경로에 대한 요청을 보낼 수 있는 버튼이 제공됩니다.
4.2 ReDoc
FastAPI는 또한 ReDoc을 통해 API 문서화를 지원합니다.
ReDoc은 깔끔하고 현대적인 디자인으로 복잡한 API를 쉽게 탐색할 수 있도록 도와줍니다.
ReDoc 문서는 ‘/redoc’ 경로에서 확인할 수 있습니다.
ReDoc 예제
FastAPI 애플리케이션을 실행한 후, 웹 브라우저에서 ‘http://localhost:8000/redoc’를
열어보세요. ReDoc으로 생성된 API 문서를 확인할 수 있습니다.
각 API Endpoint에 대한 설명과 요청/응답 모델을 간결하게 보여줍니다.
5. FastAPI의 문서화에 대한 추가적인 기능
FastAPI는 문서화 기능을 강화하기 위한 여러 가지 옵션을 제공합니다.
예를 들어, API 문서화 시에 사용할 제목, 설명 및 버전 정보를 설정할 수 있습니다.
예제 코드
from fastapi import FastAPI
app = FastAPI(
title="My API",
description="API 설명을 여기에 적습니다.",
version="1.0.0",
)
@app.get("/")
def read_root():
return {"Hello": "World"}
위와 같이 FastAPI 인스턴스를 생성할 때, title, description, version 등의
매개변수를 지정할 수 있습니다. 이렇게 하면 Swagger UI와 ReDoc에 설정한 값이
자동으로 반영됩니다.
6. 의존성과 보안 기능을 활용한 문서화
FastAPI는 API 문서화를 단순화하는 것만이 아니라, 의존성 주입(Dependency Injection)와 보안
기능을 통해 API의 복잡한 구조를 관리하는 데도 유용합니다. 예를 들어,
인증이 필요한 API Endpoint의 경우 FastAPI는 이러한 기능을 문서화하는 데 있어서
유용한 정보를 제공합니다.
예제 코드
from fastapi import FastAPI, Depends
app = FastAPI()
def fake_authenticate(username: str, password: str):
if username == "admin" and password == "secret":
return True
return False
@app.get("/secure-data/")
def get_secure_data(authenticated: bool = Depends(fake_authenticate)):
return {"data": "This is secured data"}
위 예제를 실행할 경우 ‘/secure-data/’ Endpoint는 ‘fake_authenticate’ 함수를 통해
인증을 요구합니다. Swagger UI에서는 이 Endpoint에 대해 인증 요구 사항이
명시적으로 표시될 것입니다.
7. 결론
FastAPI는 훌륭한 자동 문서화 기능을 제공하여 API 개발을 보다 쉽게 만들어 줍니다.
Swagger UI와 ReDoc을 통해 API 문서를 자동으로 생성할 수 있는 기능은 개발자에게 큰
시간을 절약하게 하며, 적시에 문서화된 API를 제공할 수 있습니다.
또한 FastAPI의 다양한 기능을 통해 애플리케이션의 안정성과 보안성을 높일 수 있습니다.
FastAPI를 사용한 API 개발의 모든 과정을 이해하는 데 도움이 되었기를 바랍니다.
앞으로도 FastAPI를 활용하여 더 나은 웹 애플리케이션을 개발해 보세요!