Corpo - Campos¶

🌐 Tradução por IA e humanos

Esta tradução foi feita por IA orientada por humanos. 🤝

Ela pode conter erros de interpretação do significado original ou soar pouco natural, etc. 🤖

Você pode melhorar esta tradução ajudando-nos a orientar melhor o LLM de IA.

Da mesma forma que você pode declarar validações adicionais e metadados nos parâmetros de uma função de operação de rota com Query, Path e Body, você pode declarar validações e metadados dentro de modelos do Pydantic usando Field do Pydantic.

Importe `Field`¶

Primeiro, você tem que importá-lo:

Python 3.10+

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item = Body(embed=True)):
    results = {"item_id": item_id, "item": item}
    return results

Atenção

Note que Field é importado diretamente do pydantic, não do fastapi como todo o resto (Query, Path, Body, etc).

Declare atributos do modelo¶

Você pode então utilizar Field com atributos do modelo:

Python 3.10+

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item = Body(embed=True)):
    results = {"item_id": item_id, "item": item}
    return results

Field funciona da mesma forma que Query, Path e Body, ele possui todos os mesmos parâmetros, etc.

Detalhes Técnicos

Na realidade, Query, Path e outros que você verá em seguida, criam objetos de subclasses de uma classe Param comum, que é ela mesma uma subclasse da classe FieldInfo do Pydantic.

E Field do Pydantic retorna uma instância de FieldInfo também.

Body também retorna objetos de uma subclasse de FieldInfo diretamente. E tem outras que você verá mais tarde que são subclasses da classe Body.

Lembre-se que quando você importa Query, Path, e outros de fastapi, esse são na realidade funções que retornam classes especiais.

Dica

Note como cada atributo do modelo com um tipo, valor padrão e Field possuem a mesma estrutura que parâmetros de funções de operações de rota, com Field ao invés de Path, Query e Body.

Adicione informações extras¶

Você pode declarar informação extra com json_schema_extra em Field, Query, Body, etc. E isso será incluído no JSON Schema gerado.

Você irá aprender mais sobre adicionar informações extras posteriormente nessa documentação, quando estiver aprendendo a declarar exemplos.

Atenção

Chaves extras passadas em json_schema_extra também estarão presentes no schema OpenAPI resultante da sua aplicação. Como essas chaves podem não fazer necessariamente parte da especificação OpenAPI, algumas ferramentas de OpenAPI, por exemplo o validador do OpenAPI, podem não funcionar com o schema gerado.

Recapitulando¶

Você pode usar Field do Pydantic para declarar validações extras e metadados para atributos do modelo.

Você também pode usar json_schema_extra para passar metadados do JSON Schema adicionais.