FastAPI: campos del cuerpo de solicitud y modelos anidados

Dentro de los modelos Pydantic, puedes usarFieldpara declarar reglas de validación y metadatos para los campos, y también puedes anidar modelos para manejar estructuras de datos JSON complejas.


Declarar la validación de campos con Field

Al igual que en las funciones de operación de ruta se usaQuery、Pathde la misma manera que se declara la validación, dentro de los modelos Pydantic se usaFieldpara declarar la validación de campos:

Ejemplo

from typing import Annotated
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100, description="Nombre del producto")  # Obligatorio, de 1 a 100 caracteres
    description: str | None = Field(default=None, max_length=300, description="Descripción del producto")  # Opcional
    price: float = Field(gt=0, description="Precio del producto")  # Obligatorio, debe ser mayor que 0
    tax: float | None = Field(default=None, ge=0, description="Impuesto")  # Opcional, >= 0


@app.post("/items/")
async def create_item(item: Item):
    return item

FieldParámetros de validación admitidos:

Tipo de parámetroParámetroDescripción
Validación de cadenasmin_lengthLongitud mínima
max_lengthLongitud máxima
patternCoincidencia de expresión regular
Validación numéricagtMayor que
geMayor o igual que
ltMenor que
leMenor o igual que
MetadatostitleTítulo del campo
descriptionDescripción del campo

NotaFielddesdepydanticImportar, y no desdefastapiimportar. Esto es diferente deQuery、Pathetc., desdefastapila importación es diferente.


Campos de tipo lista

Puedes declarar un campo como lista y especificar el tipo de sus elementos:

Ejemplo

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []  # Lista de cadenas, por defecto lista vacía


@app.post("/items/")
async def create_item(item: Item):
    return item

Ejemplo de cuerpo de solicitud:

{
    "name": "Foo",
    "price": 42.0,
    "tags": ["rock", "metal", "bar"]
}

Usar Set para eliminar duplicados

Si las etiquetas no deben repetirse, usa elsettipo:

Ejemplo

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()  # Elimina automáticamente etiquetas duplicadas

Incluso si la solicitud contiene etiquetas duplicadas, se eliminarán automáticamente en la respuesta.


Modelos anidados

El tipo de un campo de un modelo Pydantic puede ser otro modelo Pydantic, admitiendo anidamiento a cualquier profundidad:

Ejemplo

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


# Submodelo: Imagen
class Image(BaseModel):
    url: HttpUrl      # Valida automáticamente si es una URL válida
    name: str


# Modelo principal: Producto, incluye el submodelo Imagen
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None  # Información de imagen opcional


@app.post("/items/")
async def create_item(item: Item):
    return item

La estructura correspondiente del cuerpo de solicitud:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2,
    "tags": ["rock", "metal", "bar"],
    "image": {
        "url": "http://example.com/baz.jpg",
        "name": "The Foo live"
    }
}

Submodelos en listas

Puedes colocar submodelos en una lista:

Ejemplo

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None  # Lista de imágenes


@app.post("/items/")
async def create_item(item: Item):
    return item

El cuerpo de solicitud correspondiente:

{
    "name": "Foo",
    "price": 42.0,
    "images": [
        {"url": "http://example.com/baz.jpg", "name": "The Foo live"},
        {"url": "http://example.com/dave.jpg", "name": "The Baz"}
    ]
}

Modelos profundamente anidados

Puedes definir estructuras anidadas de cualquier profundidad:

Ejemplo

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None


class Offer(BaseModel):
    name: str
    description: str | None = None
    price: float
    items: list[Item]  # Offer contiene varios Item, e Item contiene varias Image


@app.post("/offers/")
async def create_offer(offer: Offer):
    return offer

Cuerpo de solicitud de lista pura

Si la capa más externa del cuerpo de solicitud es un array JSON, puedes declarar el tipo lista directamente en los parámetros de la función:

Ejemplo

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


# El cuerpo de solicitud es directamente una lista de Image
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

Cuerpo de solicitud compuesto por un dict arbitrario

Cuando necesitas recibir datos de diccionario cuyas claves no son fijas, puedes declarar undicttipo de cuerpo de solicitud:

Ejemplo

from fastapi import FastAPI

app = FastAPI()


# Recibe un diccionario con claves int y valores float
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
    return weights

Ejemplo de cuerpo de solicitud:

{
    "1": 0.5,
    "2": 1.5,
    "3": 2.0
}

JSON solo admite claves de tipo cadena, pero Pydantic convierte automáticamente las claves de cadena al tipo declarado (como en este ejemplo,int)。


Resumen

  • Usando PydanticFieldpara agregar validación y metadatos a los campos del modelo
  • list[str]、set[str]Los tipos de colección, etc., pueden declarar campos de lista/conjunto
  • Los modelos pueden anidarse, admitiendo estructuras JSON de cualquier profundidad.
  • HttpUrly otros tipos especiales validan automáticamente el formato.
  • Las listas puras y los diccionarios arbitrarios también pueden usarse como tipo de cuerpo de solicitud.
Otras extensiones