当前位置：物联沃-IOTWORD物联网 > 技术教程 > python-fastapi接口以及传参编写
代码收藏家代码收藏家 技术教程

python-fastapi接口以及传参编写

接口编写

接口方法

@app.get("/items/")
async def read_items():
  return true

路径操作

POST：创建数据。
GET：读取数据。
PUT：更新数据。
DELETE：删除数据。

路径内置参数
operation_id 是一个唯一的标识符，用于唯一地标识每个 API 操作。
summary 参数将用可以作为操作的简短标题。
description 参数可以为接口提供更详细的说明。
tags参数允许您将相关的 API 操作归类到不同的组中。

@app.post("/items/", operation_id="create_item_operation", summary="创建项目", description="用于创建一个新的项目)
async def create_item(item: Item):
    return {"item": item}
@app.post("/items/", tags=["items"], summary="创建项目")
async def create_item(item: Item):
    return {"item": item}

参数

路径参数

int将路径参数转换为整数。
float将路径参数转换为浮点数。
str（默认）：保持路径参数为字符串，可以不写。
path用于匹配包含斜杠的路径片段。

以下为单参数和复核参数，即便有设置默认值也不能传空，路径参数属于必传项

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}
@app.get("/users/{user_id}/items/{item_id:int}")
async def read_user_item(user_id: str, item_id: int = None):
    if item_id is not None:
        return {"user_id": user_id, "item_id": item_id}
    else:
        return {"user_id": user_id, "message": "Item ID not provided"}

查询参数

在参数后设置 | None = None即代表这个参数值可传可不传，设置= false等赋值操作则意味着，如果该参数为空则传入这个设定的默认值

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None, short: bool = False):
    if q:
        return {"item_id": item_id, "q": q,"short": short}
    return {"item_id": item_id,"short": short}

请求体

请求体也可以整体设置 | None = None，但是这样需要加上实体是否为空的判断。同样也可以在设定的 Pydantic 模型中选择字段加上。

from fastapi import FastAPI
from pydantic import BaseModel


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


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

参数校验

Query 对象用于定义和验证查询参数。在这个例子中：
default=None：设置 q 参数的默认值为 None。这意味着如果请求中没有提供 q 参数，则它将被赋予 None。
max_length=50：限制 q 参数的最大长度为 50 个字符。如果提供的值超过这个长度，FastAPI 将返回一个验证错误。
min_length=3：限制 q 参数的最小长度为 50 个字符。如果提供的值低于这个长度，FastAPI 将返回一个验证错误。
q: Union[str, None] 等价于q: str | None

from typing import Union

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Union[str, None] = Query(default=None, min_length=3, max_length=50),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Query常用参数

default设置查询参数的默认值。如果不提供该参数，则使用此默认值。
示例：Query(default=None)
alias使用别名来指定查询参数的名称。例如，可以将查询参数命名为 item-query，但在函数中使用 q。
示例：Query(alias=“item-query”)
title 和 description用于在生成的 OpenAPI 文档中为查询参数添加标题和描述。这有助于提高 API 文档的可读性和用户体验。
示例：Query(title=“Item Query”, description=“A query parameter for item filtering”)
deprecated标记查询参数为已弃用（deprecated），这会在生成的文档中标记出来。
示例：Query(deprecated=True)
include_in_schema控制是否在生成的 OpenAPI 文档中包含此查询参数。默认为 True，可以设置为 False 来隐藏某些内部或敏感参数。
示例：Query(include_in_schema=False)
gt, ge, lt, le分别表示大于 (gt)、大于等于 (ge)、小于 (lt)、小于等于 (le)。
适用于数值类型的查询参数。
示例：Query(gt=0, le=100) 表示参数必须大于 0 且小于等于 100。
min_length, max_length限制字符串类型的查询参数的最小和最大长度。
示例：Query(min_length=3, max_length=50)
regex使用正则表达式来验证查询参数的格式。例如，验证电子邮件地址或特定格式的字符串。
示例：Query(regex=“1+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$”)
list允许查询参数接受多个值，并返回一个列表。
示例：Query(None) 可以通过 ?q=value1&q=value2 接收多个值。

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(
        default=None,
        alias="item-query",
        title="Item Query",
        description="A query parameter for item filtering",
        deprecated=False,
        include_in_schema=True,
        min_length=3,
        max_length=50,
        regex="^[a-zA-Z0-9_]+$"
    ),
    price: float | None = Query(default=None, gt=0, le=100),
    tags: list[str] | None = Query(default=None)
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    if price is not None:
        results.update({"price": price})
    if tags:
        results.update({"tags": tags})
    return results

查询参数模型

Annotated来自 Python 的标准库 typing，用于添加额外的元数据到类型提示中。FastAPI 使用它来关联依赖项或验证器。
Literal：允许定义固定值的集合，确保变量只能取这些预定义的值之一。
FastAPI 和 Query分别用于创建 FastAPI 应用实例和定义查询参数。
BaseModel 和 Field来自 Pydantic，用于定义数据模型和字段约束。

from typing import Annotated, Literal

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

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

星号(*):表示后续的所有参数都必须是关键字参数（keyword-only arguments）。这意味着当调用此函数时，这些参数必须显式地命名传递。这样可以提高代码的可读性和明确性。
Body: 这是 FastAPI 中的一个函数，用于从 HTTP 请求的 body 中提取数据并进行类型验证。比如name: str = Body(…, alias=“name”)，name: str = Body(…)
**Body(gt=0) **是 FastAPI 等框架中用来做请求体验证的一种方式。它表示在接受 HTTP 请求时，参数值需要满足某些条件。在这个例子中：
Annotated[int, Body(gt=0)] 表示importance 参数是一个整数，并且它来自请求体（通过 Body 注解）。
这个整数必须大于 0（通过 gt=0 验证规则）。

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


class User(BaseModel):
    username: str
    full_name: str | None = None


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

Body(embed=True) 这是一个依赖注入器，用于指定 item 参数是从请求体中提取的，并且应该嵌套在一个单一的 JSON 对象中。具体来说，embed=True 表示 FastAPI 期望请求体包含一个顶层键（例如 item），而实际的 Item 数据作为该键的值

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

如果想要查询更详细内容可以前往fastapi官网查看

  1. a-zA-Z0-9_.± ↩︎

作者：CCCout

物联沃分享整理
物联沃-IOTWORD物联网 » python-fastapi接口以及传参编写

代码收藏家 普通

分享到：

相关推荐

发表回复