FastAPI로 Docusaurus와 유사한 사이트 구축하기: 1단계 - HTML 템플릿

다양한 문서 사이트 도구들이 있지만, 사용하면서 좌절감을 느낀 적이 있을 것입니다. 모든 특정 요구 사항을 충족하면서 사용하기에 충분히 단순한 단일 도구는 없는 것 같습니다.

그렇다면 자신만의 것을 구축해 보는 것은 어떨까요?

이하 시리즈 기사에서는 Docusaurus와 유사한 문서 사이트를 점진적으로 구축할 것입니다.

이것은 첫 번째 기사입니다. 동적 HTML 템플릿 페이지를 반환하는 간단한 백엔드 서비스를 구축하는 것으로 시작하겠습니다.

1단계: 환경 설정 및 종속성 설치

먼저 프로젝트 디렉토리를 생성하고 필요한 종속성을 설치해야 합니다.

프로젝트 디렉토리 생성:

mkdir fastapi-docs-site
cd fastapi-docs-site

핵심 종속성 설치: 세 가지 주요 라이브러리를 설치할 것입니다:

fastapi: 웹 프레임워크.
uvicorn[standard]: FastAPI를 실행할 ASGI 서버.
jinja2: HTML 템플릿 렌더링에 사용되는 엔진.

pip install fastapi "uvicorn[standard]" jinja2

2단계: 프로젝트 스켈레톤 설정

다음으로 fastapi-docs-site 루트 디렉토리에 다음 파일과 폴더를 만듭니다.

fastapi-docs-site/
├── main.py           # 메인 FastAPI 애플리케이션 파일
├── static/           # CSS, JS, 이미지와 같은 정적 파일 저장용
└── templates/        # Jinja2 HTML 템플릿 저장용

main.py: 모든 FastAPI 애플리케이션 로직과 라우트가 포함될 파일입니다.
templates/: Jinja2는 기본적으로 여기에 HTML 템플릿 파일을 찾습니다.
static/: FastAPI는 이 디렉토리를 사용하여 정적 파일을 제공합니다 (향후 기사에서 사용).

3단계: 첫 번째 FastAPI 앱 작성 (JSON 버전)

템플릿 렌더링을 시작하기 전에 FastAPI 자체가 제대로 작동하는지 먼저 확인해 보겠습니다.

main.py를 열고 다음 기본 코드를 입력합니다.

# main.py
from fastapi import FastAPI

# FastAPI 앱 인스턴스화
app = FastAPI()

@app.get("/")
async def root():
    """
    루트 라우트, 간단한 JSON 응답 반환
    """
    return {"message": "Hello FastAPI"}

터미널을 열고 fastapi-docs-site 루트 디렉토리에 있는지 확인한 후 실행합니다.

uvicorn main:app --reload

main:app은 main.py에서 생성된 app = FastAPI() 인스턴스를 참조합니다.
--reload: 이 매개변수는 코드 변경 사항을 감시하고 서버를 자동으로 다시 시작합니다.

이제 브라우저를 열고 http://127.0.0.1:8000으로 이동합니다. 다음과 같이 표시되어야 합니다.

{ "message": "Hello FastAPI" }

4단계: Jinja2 템플릿 엔진 구성

좋습니다. 서버가 실행 중입니다. 그러나 JSON이 아닌 HTML을 원합니다.

FastAPI에 templates 디렉토리를 찾고 사용하는 방법을 알려야 합니다.

main.py를 수정합니다.

# main.py
from fastapi import FastAPI
# Jinja2Templates 가져오기
from fastapi.templating import Jinja2Templates

# FastAPI 앱 인스턴스화
app = FastAPI()

# 핵심 단계: 템플릿 디렉토리 구성
# "templates" 문자열은 생성한 폴더 이름과 일치해야 합니다.
templates = Jinja2Templates(directory="templates")


@app.get("/")
async def root():
    # 지금은 이대로 둡니다. 다음 단계에서 변경할 것입니다.
    return {"message": "Hello FastAPI"}

5단계: 첫 번째 HTML 템플릿 생성

templates/ 폴더에 index.html이라는 새 파일을 만듭니다.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Docs Site</title>
  </head>
  <body>
    <h1>{{ page_title }}</h1>
    <p>Welcome to our first dynamic page!</p>
  </body>
</html>

<h1>{{ page_title }}</h1>에 주목하세요. 이것은 순수한 HTML이 아닙니다. {{ ... }}는 Jinja2의 변수 구문입니다. 곧 "Homepage"와 같은 값을 동적으로 FastAPI 백엔드에서 이 page_title 변수로 전달할 것입니다.

6단계: TemplateResponse로 템플릿 렌더링

마지막 단계입니다. 루트 라우트 /를 수정하여 더 이상 JSON을 반환하지 않고 index.html 템플릿을 렌더링하도록 합니다.

이를 위해 다음 도구를 가져와야 합니다.

Request: Jinja2가 올바른 URL과 컨텍스트를 구축할 수 있도록 하는 데 필요합니다.
HTMLResponse: FastAPI에서 HTML 반환을 위해 특별히 제공하는 응답 클래스입니다.

main.py를 다음과 같이 수정합니다.

# main.py
from fastapi import FastAPI, Request  # Request 가져오기
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse # HTMLResponse 가져오기

app = FastAPI()

templates = Jinja2Templates(directory="templates")


# 참고: 라우트 함수 시그니처에 이제 request: Request가 포함됩니다.
@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    """
    루트 라우트, 렌더링된 HTML 템플릿 반환
    """
    # 1. 템플릿 파일 이름
    template_name = "index.html"

    # 2. 템플릿에 전달할 컨텍스트
    #    "request"가 필요합니다.
    #    "page_title"은 우리의 사용자 지정 변수로, HTML의 {{ page_title }}에 해당합니다.
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!"
    }

    return templates.TemplateResponse(template_name, context)