Как добавить примеры данных для моделей Pydantic в документацию FastAPI (Swagger UI)?

Question

Как добавить примеры данных для моделей Pydantic в документацию FastAPI (Swagger UI)?

Тип вопроса: Библиотеки и модули Вероятность: 10% Категория: Python Разработчик

Ответ

Для добавления примеров данных для моделей Pydantic, которые будут отображаться в интерактивной документации FastAPI (Swagger UI), используется вложенный класс Config с атрибутом schema_extra.

Это позволяет наглядно продемонстрировать ожидаемую структуру JSON для запросов и ответов, что значительно упрощает тестирование и интеграцию API для других разработчиков.

Пример:

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Item(BaseModel):
    name: str = Field(..., description="Название товара")
    price: float = Field(..., description="Цена товара")

    class Config:
        # Словарь в schema_extra будет использован как пример в OpenAPI схеме
        schema_extra = {
            "example": {
                "name": "My Awesome Item",
                "price": 99.99
            }
        }

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

В сгенерированной документации /docs для эндпоинта /items/ в разделе Request body будет отображаться указанный пример, а также описания полей из Field.

Ответ 18+ 🔞

А, ну это ж классика, блядь! Смотри, как тут всё просто, но дохуя полезно.

Вот представь: ты пишешь API на FastAPI, и тебе надо, чтобы другие разработчики не гадали, какую хуйню тебе в запросе слать. Чтобы они прямо в документации (/docs) видели готовый пример JSON'а, как на блюдечке. И чтобы не пришлось им в личку писать: "чувак, смотри, вот такую структуру жду, а то у тебя там price строкой прилетает, а надо числом, ёпта".

Так вот, для этого в Pydantic-моделях есть такая хитрая жопа — вложенный класс Config. И в нём можно прописать schema_extra. Это как записка на холодильник: "Смотри, мудила, вот так должно выглядеть!"

Сам смотри, как это выглядит в коде:

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Item(BaseModel):
    name: str = Field(..., description="Название товара")
    price: float = Field(..., description="Цена товара")

    class Config:
        # Словарь в schema_extra будет использован как пример в OpenAPI схеме
        schema_extra = {
            "example": {
                "name": "My Awesome Item",
                "price": 99.99
            }
        }

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

И что получается? Заходишь ты в Swagger UI (это та самая интерактивная документация по адресу /docs), открываешь эндпоинт /items/, а там — охуенно! — прямо в окошке для тела запроса уже лежит этот самый пример: {"name": "My Awesome Item", "price": 99.99}. И под полями ещё описания из Field висят. Красота, блядь, а не жизнь!

Вот так, без всяких танцев с бубном, ты делаешь свой API понятным даже для того полупидора, который вчера только с Hello World разобрался. Удобно же, ёпта?