ImQi1云笔记

外观

Request Body请求体

什么是请求体

将数据从客户端发送到服务器时，可以将其作为请求体发送。请求体是客户端发送到API的数据，响应体是API发送到客户端的数据。API几乎总是必须发送一个响应体，但是客户端并不需要一直发送请求体。

定义请求体需要使用pydantic模型，不能通过GET请求发送请求体。发送请求体数据，必须使用POST、PUT、DELETE、PATCH等请求。

创建数据模型

  1. 定义模型。需要从pydantic中导入BaseModel，代码如下：
from pydantic import BaseModel
  1. 创建模型。声明数据模型为一个类，且继承自BaseModel类，代码如下：
class Item(BaseModel):
    name: str
    desc: str = None
    price: float
    tax: float = None

和Query参数一样，数据类型如果不是必须的话，可以拥有一个默认值。否则，该属性就是必须的。使用None可以让该数据变为可选的。

上面的Item模型可声明为一个JSON对象或Pythondict，如：

{
    'name': 'Foo',
    'desc': 'An optional description',
    'price': 12.3,
    'tax': 3.5
}

desc属性和tax属性是可选的，所以下方的JSON值也是有效的：

{
    'name': 'Foo',
    'price': 12.3
}
  1. 将模型定义为参数。将上方定义的模型添加到路径操作中，和定义Path和Query参数的方法一样，代码如下：
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    desc: str = None
    price: float
    tax: float = None

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

声明参数的类型为创建的Item类型。

使用Request Body有以下好处：

  • 将请求的正文读取为JSON类型。
  • 转换相应的类型。
  • 验证数据。若数据无效，它会指出错误所在。
  • 在参数item中提供接收的数据。
  • 这些Schemas将是生成的OpenAPI Schema的一部分，并由自动文档UI使用。

模型的JSON Schenma将成为OpenAPI Schema的一部分，显示在交互式API文档中，并可在需要的路径操作的API文档中使用，如下图。

交互式API文档
交互式API文档

同时定义Path参数、Query参数和Request Body参数

下面通过一个实例介绍如何同时定义这三个参数。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    desc: str = None
    price: float
    tax: float = None

@app.post('/items/{item_id}')
async def create_item(item: Item, item_id: int, short: bool):
    result = {'item_id': item_id, **item.model_dump()}
    if short:
        return result.update({'short': short})
    return result

FastAPI识别参数的步骤如下：

  • 若在Path中声明了该参数，它将用作path参数。
  • 若参数为单一类型（如int类型），它将被解释为query参数。
  • 若参数声明为pydantic模型的类型，它将被解释为请求体。

在交互式API文档中添加了参数，点击Execute按钮，运行结果如下图。

添加参数
添加参数

许可证：署名 4.0 国际 (CC-BY-4.0)

2026 © 棋