FastAPI（15）- 声明请求示例数据（下）-阿里云开发者社区

FastAPI（15）- 声明请求示例数据（下）

2022-05-15 185

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

简介： FastAPI（15）- 声明请求示例数据（下）

OpenAPI 中的 example、examples 参数

当使用 FastAPI 提供的

Path()
Query()
Header()
Cookie()
Body()
Form()
File()

可以声明一个 example 或 examples 参数，FastAPI 会自动将 example、examples 的值添加到 OpenAPI 文档中

总结

Pydantic 并没有直接支持 example 参数，而 FastAPI 进行了扩展，直接支持添加 example、examples 参数

使用 Body() ，添加 example 参数

#!usr/bin/env python
# -*- coding:utf-8 _*-
"""
# author: 小菠萝测试笔记
# blog:  https://www.cnblogs.com/poloyy/
# time: 2021/9/19 9:40 下午
# file: 12_model.py
"""
from typing import Optional
import uvicorn
from pydantic import BaseModel
from fastapi import FastAPI, Body
app = FastAPI()
class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None
@app.put("/items/{item_id}")
async def update_item(
        item_id: int,
        item: Item = Body(
            default=...,
            description="描述",
            # 添加一个 example 参数
            example={
                "name": "body name",
                "description": "body 描述",
                "price": 3.33,
                "tax": 5.55
            },
        ),
):
    results = {"item_id": item_id, "item": item}
    return results
if __name__ == "__main__":
    uvicorn.run(app="13_example:app", host="127.0.0.1", port=8080, reload=True, debug=True)

查看 Swagger API 文档

Schema 并不会显示 example 的值哦

使用 Body() ，添加 examples 参数

examples

本身是一个 dict，每个键标识一个具体的示例，而键对应的值也是一个 dict

每个示例 dict 可以包含

summary：简短描述
description：可以包含 markdown 文本的长描述
value：显示的示例值
externalValue：替代值，指向示例的 URL（不怎么用）

实际代码

#!usr/bin/env python
# -*- coding:utf-8 _*-
"""
# author: 小菠萝测试笔记
# blog:  https://www.cnblogs.com/poloyy/
# time: 2021/9/19 9:40 下午
# file: 12_model.py
"""
from typing import Optional
import uvicorn
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body
app = FastAPI()
class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None
@app.put("/items/{item_id}")
async def update_item(
        *,
        item_id: int,
        item: Item = Body(
            default=...,
　　　　　　  # 三个键，代表三个不一样的示例值
            examples={
                "normal": {
                    "summary": "正常的栗子",
                    "description": "A **normal** item works correctly.",
                    "value": {
                        "name": "Foo",
                        "description": "A very nice Item",
                        "price": 35.4,
                        "tax": 3.2,
                    },
                },
                "converted": {
                    "summary": "会自动转换类型的栗子",
                    "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                    "value": {
                        "name": "Bar",
                        "price": "35.4",
                    },
                },
                "invalid": {
                    "summary": "校验失败的栗子",
                    "value": {
                        "name": "Baz",
                        "price": "thirty five point four",
                    },
                },
            },
        ),
):
    results = {"item_id": item_id, "item": item}
    return results
if __name__ == "__main__":
    uvicorn.run(app="13_example:app", host="127.0.0.1", port=8080, reload=True, debug=True)