Eine Docusaurus-ähnliche Seite mit FastAPI erstellen: Schritt 1 - HTML-Vorlage

Es gibt viele Tools zur Erstellung von Dokumentations-Websites, aber wie Sie wahrscheinlich festgestellt haben, ist keines davon für alle Ihre spezifischen Bedürfnisse geeignet und gleichzeitig einfach genug zu bedienen.

Wenn das der Fall ist, warum bauen Sie nicht Ihre eigene?

In der folgenden Artikelreihe werden wir schrittweise eine Dokumentations-Website ähnlich wie Docusaurus erstellen.

Dies ist der erste Artikel. Wir beginnen mit dem Erstellen eines einfachen Backend-Dienstes, der eine dynamische HTML-Vorlagenseite zurückgibt.

Schritt 1: Umgebungs-Setup und Installation von Abhängigkeiten

Zuerst müssen wir ein Projektverzeichnis erstellen und die notwendigen Abhängigkeiten installieren.

Erstellen Sie das Projektverzeichnis:

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

Installieren Sie die Kernabhängigkeiten: Wir werden drei Schlüsselbibliotheken installieren:

fastapi: Unser Web-Framework.
uvicorn[standard]: Der ASGI-Server zum Ausführen von FastAPI.
jinja2: Die Engine, die zum Rendern von HTML-Vorlagen verwendet wird.

pip install fastapi "uvicorn[standard]" jinja2

Schritt 2: Erstellen des Projektgerüsts

Erstellen Sie als Nächstes die folgenden Dateien und Ordner im Stammverzeichnis von fastapi-docs-site:

fastapi-docs-site/
├── main.py           # Unsere Haupt-FastAPI-Anwendungsdatei
├── static/           # Zum Speichern von statischen Dateien wie CSS, JS, Bilder
└── templates/        # Zum Speichern von Jinja2 HTML-Vorlagen

main.py: Hier wird die gesamte Logik und die Routen unserer FastAPI-Anwendung gespeichert.
templates/: Jinja2 sucht hier standardmäßig nach HTML-Vorlagendateien.
static/: FastAPI wird dieses Verzeichnis verwenden, um statische Dateien bereitzustellen (wir werden dies in einem zukünftigen Artikel verwenden).

Schritt 3: Schreiben Sie Ihre erste FastAPI-App (JSON-Version)

Bevor wir mit dem Rendern von Vorlagen beginnen, stellen wir zunächst sicher, dass FastAPI selbst korrekt funktioniert.

Öffnen Sie main.py und geben Sie den folgenden Basiscode ein:

# main.py
from fastapi import FastAPI

# Instanziieren Sie die FastAPI-App
app = FastAPI()

@app.get("/")
async def root():
    """
    Root-Route, gibt eine einfache JSON-Antwort zurück
    """
    return {"message": "Hello FastAPI"}

Öffnen Sie Ihr Terminal, stellen Sie sicher, dass Sie sich im Stammverzeichnis von fastapi-docs-site befinden, und führen Sie aus:

uvicorn main:app --reload

main:app bezieht sich auf die app = FastAPI()-Instanz, die in main.py erstellt wurde.
--reload: Dieser Parameter überwacht Ihre Codeänderungen und startet den Server automatisch neu.

Öffnen Sie nun Ihren Browser und besuchen Sie http://127.0.0.1:8000. Sie sollten sehen:

{ "message": "Hello FastAPI" }

Schritt 4: Konfigurieren Sie die Jinja2-Vorlagen-Engine

Großartig, der Server läuft. Aber wir wollen HTML, nicht JSON.

Wir müssen FastAPI mitteilen, wie das templates-Verzeichnis gefunden und verwendet wird.

Ändern Sie main.py:

# main.py
from fastapi import FastAPI
# Importieren Sie Jinja2Templates
from fastapi.templating import Jinja2Templates

# Instanziieren Sie die FastAPI-App
app = FastAPI()

# Wichtiger Schritt: Konfigurieren Sie das Vorlagenverzeichnis
# Der String "templates" muss mit dem von Ihnen erstellten Ordnernamen übereinstimmen
templates = Jinja2Templates(directory="templates")


@app.get("/")
async def root():
    # Behalten Sie dies vorerst bei, wir werden es im nächsten Schritt ändern
    return {"message": "Hello FastAPI"}

Schritt 5: Erstellen Sie unsere erste HTML-Vorlage

Erstellen Sie im Ordner templates/ eine neue Datei: 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>

Beachten Sie <h1>{{ page_title }}</h1>. Das ist kein reines HTML. {{ ... }} ist die Variablensyntax von Jinja2. Wir werden bald einen Wert (wie "Homepage") dynamisch von unserem FastAPI-Backend an diese page_title-Variable übergeben.

Schritt 6: Rendern der Vorlage mit TemplateResponse

Letzter Schritt: Ändern wir die Root-Route / so, dass sie kein JSON mehr zurückgibt, sondern stattdessen unsere index.html-Vorlage rendert.

Dazu müssen wir die folgenden Werkzeuge importieren:

Request: Dies ist erforderlich, damit Jinja2 korrekt URLs und Kontext erstellen kann.
HTMLResponse: Eine von FastAPI bereitgestellte Antwortklasse speziell für die Rückgabe von HTML.

Ändern Sie main.py wie folgt:

# main.py
from fastapi import FastAPI, Request  # Importieren Sie Request
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse # Importieren Sie HTMLResponse

app = FastAPI()

templates = Jinja2Templates(directory="templates")


# Hinweis: Die Signatur der Routenfunktion enthält jetzt request: Request
@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    """
    Root-Route, gibt die gerenderte HTML-Vorlage zurück
    """
    # 1. Der Name der Vorlagendatei
    template_name = "index.html"

    # 2. Der an die Vorlage zu übergebende Kontext
    #    "request" ist erforderlich
    #    "page_title" ist unsere benutzerdefinierte Variable, die {{ page_title }} im HTML entspricht
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!"
    }

    return templates.TemplateResponse(template_name, context)

Wenn Sie --reload aktiviert hatten, sollte Ihr Server automatisch neu gestartet worden sein.

Aktualisieren Sie die Seite http://127.0.0.1:8000.

Sie werden feststellen, dass das JSON verschwunden ist, ersetzt durch eine gerenderte HTML-Seite, und der Inhalt des <h1>-Tags wurde dynamisch ersetzt.

Bereitstellung des Projekts online

Eine Dokumentations-Website soll von jedem besucht werden können, daher reicht es nicht aus, sie nur lokal auszuführen. Als Nächstes können wir sie online bereitstellen.

Eine einfache Bereitstellungsoption ist die Verwendung von Leapcell. Es ist eine Web-App-Hosting-Plattform, die Projekte in verschiedenen Sprachen und Frameworks hosten kann, einschließlich FastAPI, natürlich.

Befolgen Sie die nachstehenden Schritte:

1.Registrieren Sie ein Konto auf der Website.

2.Committen Sie Ihr Projekt nach GitHub. Sie können die offizielle Dokumentation von GitHub für die Schritte konsultieren. Leapcell wird den Code später aus Ihrem GitHub-Repository ziehen.

3.Klicken Sie auf der Leapcell-Seite auf "Create Service".

4.Nachdem Sie Ihr FastAPI-Repo ausgewählt haben, sehen Sie, dass Leapcell die erforderlichen Konfigurationen automatisch ausgefüllt hat.

5.Klicken Sie unten auf "Submit" (Absenden), um die Bereitstellung zu starten. Die Bereitstellung wird schnell abgeschlossen und Sie werden zur Homepage der Bereitstellung weitergeleitet. Hier sehen Sie, dass Leapcell eine Domain bereitgestellt hat. Dies ist die Online-Adresse Ihres Blogs.

Zusammenfassung

Glückwunsch! Sie haben den ersten Schritt erfolgreich gemeistert: Ein FastAPI-Projekt eingerichtet und grundlegendes HTML-Vorlagen-Rendering implementiert.

Wenn Sie andere Dokumentations-Websites verwendet haben, haben Sie wahrscheinlich bemerkt, dass deren Inhalte nicht manuell in HTML geschrieben sind. Sie schreiben einfach Markdown, und die Webseiten werden automatisch generiert.

Im nächsten Artikel werden wir diese Kernfunktion implementieren: das dynamische Lesen einer echten Markdown-Datei (z. B. docs/hello.md), das Parsen in HTML und das Einbetten in unsere Webvorlage.