Mira la lección en vídeo
Accede al vídeo completo de esta lección y a más contenido exclusivo con el Plan Plus.
Desbloquear Plan PlusInstalación y configuración de Jinja2Templates
Hasta ahora has trabajado con FastAPI creando APIs REST que devuelven datos en formato JSON. Sin embargo, FastAPI también puede servir páginas web completas renderizando plantillas HTML. Para esto necesitamos un motor de plantillas que nos permita generar contenido dinámico.
Jinja2 es el motor de plantillas más utilizado en el ecosistema Python. Se integra perfectamente con FastAPI y nos permite crear páginas web dinámicas combinando HTML estático con datos de nuestra aplicación.
Instalación de dependencias
Para trabajar con plantillas en FastAPI necesitas instalar dos paquetes adicionales. El primero es Jinja2, que es el motor de plantillas, y el segundo es python-multipart, necesario para el manejo de formularios HTML:
pip install jinja2 python-multipart
Estas dependencias no vienen incluidas por defecto con FastAPI porque no todos los proyectos necesitan renderizar HTML. Al instalarlas por separado, mantienes tu aplicación ligera cuando solo necesitas crear APIs.
Configuración básica de Jinja2Templates
Una vez instaladas las dependencias, necesitas configurar el sistema de plantillas en tu aplicación FastAPI. La configuración se realiza importando y creando una instancia de Jinja2Templates:
from fastapi import FastAPI
from fastapi.templating import Jinja2Templates
app = FastAPI()
# Configuración del motor de plantillas
templates = Jinja2Templates(directory="templates")
El parámetro directory especifica la carpeta donde FastAPI buscará tus archivos de plantilla HTML. Es una buena práctica crear una carpeta llamada templates en la raíz de tu proyecto para mantener organizados todos los archivos HTML.
Estructura de directorios recomendada
Para trabajar de forma organizada, crea la siguiente estructura de carpetas en tu proyecto:
mi_proyecto/
├── main.py
├── templates/
│ └── (aquí irán tus archivos .html)
└── static/
├── css/
├── js/
└── images/
La carpeta templates contendrá todos tus archivos HTML, mientras que static almacenará recursos como hojas de estilo CSS, archivos JavaScript e imágenes que no cambian dinámicamente.
Configuración completa con archivos estáticos
Para servir también archivos estáticos como CSS e imágenes, necesitas configurar FastAPI para que pueda acceder a estos recursos:
from fastapi import FastAPI
from fastapi.templating import Jinja2Templates
from fastapi.staticfiles import StaticFiles
app = FastAPI()
# Configuración de plantillas
templates = Jinja2Templates(directory="templates")
# Configuración de archivos estáticos
app.mount("/static", StaticFiles(directory="static"), name="static")
La función mount() le dice a FastAPI que sirva todos los archivos de la carpeta static bajo la ruta URL /static. Esto significa que un archivo static/css/styles.css será accesible desde http://localhost:8000/static/css/styles.css.
Verificación de la configuración
Para asegurarte de que todo está configurado correctamente, crea un archivo de prueba en tu carpeta templates. Crea el archivo templates/test.html con contenido básico:
<!DOCTYPE html>
<html>
<head>
<title>Prueba de configuración</title>
</head>
<body>
<h1>¡Jinja2 está funcionando!</h1>
</body>
</html>
Con esta configuración básica ya tienes todo lo necesario para comenzar a renderizar plantillas HTML en tu aplicación FastAPI. El objeto templates que has creado será el que utilices en tus rutas para renderizar las plantillas y enviar datos dinámicos a las páginas web.
Renderizar primer template básico
Guarda tu progreso
Inicia sesión para no perder tu progreso y accede a miles de tutoriales, ejercicios prácticos y nuestro asistente de IA.
Más de 25.000 desarrolladores ya confían en CertiDevs
Con la configuración de Jinja2Templates ya lista, es momento de crear tu primera ruta que renderice HTML en lugar de devolver JSON. Este cambio fundamental te permitirá servir páginas web completas desde tu aplicación FastAPI.
Creando tu primera ruta con template
Para renderizar una plantilla HTML, necesitas modificar la forma en que defines tus rutas. En lugar de devolver directamente datos JSON, utilizarás el objeto templates que configuraste anteriormente:
from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
app = FastAPI()
templates = Jinja2Templates(directory="templates")
@app.get("/")
def home(request: Request):
return templates.TemplateResponse("index.html", {"request": request})
Observa los cambios importantes respecto a las rutas API que has usado antes:
- Importas
Requestde FastAPI para manejar la información de la petición HTTP - El parámetro
request: Requestes obligatorio para el renderizado de plantillas - Usas
templates.TemplateResponse()en lugar de devolver directamente un diccionario - El primer parámetro es el nombre del archivo de plantilla
- El segundo parámetro es un diccionario que siempre debe incluir
"request": request
Creando la plantilla HTML
Crea el archivo templates/index.html con el siguiente contenido básico:
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Mi primera página con FastAPI</title>
</head>
<body>
<h1>¡Bienvenido a FastAPI!</h1>
<p>Esta página se renderiza desde un template HTML.</p>
</body>
</html>
Al ejecutar tu aplicación con uvicorn main:app --reload y visitar http://localhost:8000/, verás una página web HTML en lugar de la respuesta JSON típica de las APIs.
Pasando datos dinámicos al template
La verdadera utilidad de los templates surge cuando necesitas mostrar datos dinámicos. Puedes pasar variables desde tu ruta Python hacia la plantilla HTML:
@app.get("/usuario/{nombre}")
def perfil_usuario(request: Request, nombre: str):
datos_usuario = {
"request": request,
"nombre_usuario": nombre,
"edad": 25,
"ciudad": "Madrid"
}
return templates.TemplateResponse("perfil.html", datos_usuario)
Usando variables en la plantilla
Crea templates/perfil.html para mostrar cómo usar las variables que pasas desde Python:
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8">
<title>Perfil de {{ nombre_usuario }}</title>
</head>
<body>
<h1>Perfil de {{ nombre_usuario }}</h1>
<div>
<p><strong>Nombre:</strong> {{ nombre_usuario }}</p>
<p><strong>Edad:</strong> {{ edad }} años</p>
<p><strong>Ciudad:</strong> {{ ciudad }}</p>
</div>
</body>
</html>
Las llaves dobles {{ }} son la sintaxis de Jinja2 para mostrar variables. Todo lo que incluyas en el diccionario de contexto estará disponible en la plantilla usando esta sintaxis.
Combinando datos de formularios
También puedes crear rutas que procesen datos y los muestren en plantillas. Por ejemplo, una ruta que reciba parámetros de consulta:
@app.get("/saludo")
def pagina_saludo(request: Request, nombre: str = "Visitante"):
contexto = {
"request": request,
"mensaje": f"¡Hola, {nombre}!",
"hora_actual": "14:30"
}
return templates.TemplateResponse("saludo.html", contexto)
Y su correspondiente plantilla templates/saludo.html:
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8">
<title>Saludo personalizado</title>
</head>
<body>
<h1>{{ mensaje }}</h1>
<p>Son las {{ hora_actual }}</p>
<a href="/?nombre=Ana">Saludar a Ana</a>
</body>
</html>
Diferencias clave con las APIs JSON
Es importante entender las diferencias fundamentales entre renderizar templates y crear APIs:
- APIs JSON: Devuelven datos estructurados que otras aplicaciones pueden consumir
- Templates HTML: Generan páginas web completas que los navegadores pueden mostrar directamente
- Flexibilidad: Puedes tener ambos tipos de rutas en la misma aplicación FastAPI
# Ruta API que devuelve JSON
@app.get("/api/usuario/{id}")
def obtener_usuario_api(id: int):
return {"id": id, "nombre": "Juan", "activo": True}
# Ruta que renderiza HTML
@app.get("/usuario/{id}")
def mostrar_usuario_web(request: Request, id: int):
return templates.TemplateResponse("usuario.html", {
"request": request,
"usuario_id": id,
"nombre": "Juan"
})
Con estos conceptos básicos ya puedes crear aplicaciones web completas que combinen la potencia de FastAPI para APIs con la capacidad de servir páginas HTML dinámicas usando Jinja2.
Aprendizajes de esta lección de FastAPI
- Instalar y configurar Jinja2 y python-multipart para renderizar plantillas en FastAPI.
- Organizar la estructura de directorios para plantillas y archivos estáticos.
- Crear rutas que devuelvan páginas HTML usando Jinja2Templates.
- Pasar datos dinámicos desde las rutas a las plantillas HTML.
- Diferenciar entre rutas que devuelven JSON y rutas que renderizan HTML en FastAPI.
Completa este curso de FastAPI y certifícate
Únete a nuestra plataforma de cursos de programación y accede a miles de tutoriales, ejercicios prácticos, proyectos reales y nuestro asistente de IA personalizado para acelerar tu aprendizaje.
Asistente IA
Resuelve dudas al instante
Ejercicios
Practica con proyectos reales
Certificados
Valida tus conocimientos
Más de 25.000 desarrolladores ya se han certificado con CertiDevs