Параметр examples
Параметр examples применяется в функциях
Path, Query, Header,
Cookie, Body, Form и File.
Он принимает список примеров значений, которые
отображаются в интерактивной документации.
Каждый пример может быть строкой, числом или словарём
с полями summary, description и value.
Синтаксис
Query(default, examples=['abcde', 'hello'])
Пример
Давайте зададим примеры для параметра запроса:
from fastapi import FastAPI, Query
app = FastAPI()
@app.get('/items/')
def read_items(q: str = Query(default=None, examples=['abcde', 'hello'])):
return {'q': q}
В документации Swagger UI параметр q будет
показан с примерами 'abcde' и 'hello'.
Пример
Давайте зададим примеры со словарями для параметра пути:
from fastapi import FastAPI, Path
app = FastAPI()
@app.get('/items/{item_id}')
def read_item(
item_id: int = Path(
examples={
'normal': {'summary': 'Normal', 'value': 1},
'large': {'summary': 'Large', 'value': 5},
},
),
):
return {'item_id': item_id}
В Swagger UI для параметра item_id появятся
два примера с описаниями 'Normal' и 'Large'.
Пример
Давайте зададим примеры для поля модели Pydantic:
<+python+>
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str = Field(examples=['abcde', 'hello'])
@app.post('/items/')
def create_item(item: Item):
return item
<-python+>
Результат выполнения кода для тела {"name": "abcde"}:
{"name": "abcde"}
Смотрите также
-
параметр
description,
который задаёт описание параметра -
параметр
title,
который задаёт заголовок параметра -
параметр
default,
который задаёт значение по умолчанию -
функция
Query,
которая описывает параметры запроса
