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)

--reload가 활성화되어 있었다면 서버가 자동으로 다시 시작되었을 것입니다.

페이지 http://127.0.0.1:8000을 새로 고칩니다.

JSON이 사라지고 렌더링된 HTML 페이지로 대체되었으며 <h1> 태그의 내용이 동적으로 변경된 것을 볼 수 있습니다.

프로젝트 온라인 배포

문서 사이트는 모든 사람이 방문할 수 있도록 만들어졌으므로 로컬에서 실행하는 것만으로는 충분하지 않습니다. 다음으로 온라인에 배포할 수 있습니다.

간단한 배포 옵션은 Leapcell을 사용하는 것입니다. FastAPI를 포함한 다양한 언어와 프레임워크의 프로젝트를 호스팅할 수 있는 웹 앱 호스팅 플랫폼입니다.

아래 단계를 따르세요.

1.웹사이트에서 계정을 등록합니다.

2.프로젝트를 GitHub에 커밋합니다. GitHub의 공식 문서를 참조하여 단계를 진행할 수 있습니다. Leapcell은 나중에 GitHub 리포지토리에서 코드를 가져올 것입니다.

3.Leapcell 페이지에서 "서비스 생성"을 클릭합니다.

4.FastAPI 리포를 선택하면 Leapcell에서 필요한 구성이 자동으로 채워진 것을 볼 수 있습니다.

5.아래의 "제출"을 클릭하여 배포합니다. 배포는 신속하게 완료되며 배포 홈페이지로 돌아갑니다. 여기에서 Leapcell에서 도메인을 제공했음을 볼 수 있습니다. 이것이 블로그의 온라인 주소입니다.

요약

축하합니다! FastAPI 프로젝트 설정 및 기본 HTML 템플릿 렌더링 구현이라는 첫 번째 단계를 성공적으로 완료했습니다.

다른 문서 사이트를 사용해 보았다면 콘텐츠가 수동으로 HTML로 작성되지 않았다는 것을 알았을 것입니다. Markdown만 작성하고 웹 페이지가 자동으로 생성됩니다.

다음 기사에서는 이 핵심 기능을 구현할 것입니다: 실제 Markdown 파일(예: docs/hello.md)을 동적으로 읽고, HTML로 파싱하고, 웹 템플릿에 삽입합니다.