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)
查看 Swagger API 文档
