FastAPIでDocusaurus風サイトを構築：ステップ1 - HTMLテンプレート

多くのドキュメンテーションサイトツールがありますが、使っていくうちにフラストレーションを感じたことがあるかもしれません。単一のツールでは、あなたの特定のニーズすべてを満たしながら、使いやすいシンプルなものであり続けることは不可能のように思えます。

もしそうなら、自分で構築してみてはいかがでしょうか？

この一連の記事では、Docusaurusに似たドキュメンテーションサイトを段階的に構築していきます。

この記事が最初です。動的なHTMLテンプレートページを返すシンプルなバックエンドサービスを構築することから始めます。

ステップ1：環境セットアップと依存関係のインストール

まず、プロジェクトディレクトリを作成し、必要な依存関係をインストールする必要があります。

プロジェクトディレクトリの作成：

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

コア依存関係のインストール： 3つの主要なライブラリをインストールします。

fastapi：Webフレームワーク。
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：HTMLの返却専用にFastAPIが提供するレスポンスクラスです。

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)