Как FastAPI генерирует автоматическую документацию?

Question

Accepted Answer

FastAPI **автоматически генерирует интерактивную документацию API** из вашего кода — ваши маршруты, параметры и модели Pydantic преобразуются в схему OpenAPI, которая обеспечивает две удобные схемы документации (Swagger UI и ReDoc) без дополнительных усилий.

## Документация бесплатно

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → endpoint description
    return item
```

Просто написав типизированные endpoints и модели, FastAPI создаёт полную документацию — нет необходимости писать или поддерживать отдельный файл документации.

## Два встроенных интерфейса документации

```text
/docs   → Swagger UI — interactive: browse endpoints AND test them in the browser
          (fill in parameters, send requests, see responses live)
/redoc  → ReDoc — a clean, readable reference-style view
/openapi.json → the raw OpenAPI schema (usable to generate client SDKs, etc.)
```

Посетите `/docs` и вы сможете изучить каждый endpoint, увидеть требуемые параметры и формы ответов, а также **отправлять реальные запросы** непосредственно из браузера — бесценно во время разработки и для потребителей API.

## Откуда берётся содержание документации

```text
Route decorators → paths, HTTP methods, tags, summaries
Type hints       → parameter types, required/optional
Pydantic models  → request/response schemas, field constraints & descriptions
Docstrings       → endpoint descriptions
Field(..., description=, example=) → field-level docs and examples
```

Всё производно из кода, который вы уже пишете — документация автоматически **остаётся в синхронизации** с реализацией.

## Обогащение документации

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## Почему это важно

Автоматическая интерактивная документация — одна из самых популярных особенностей FastAPI и главная причина его популярности.

Поскольку документация генерируется непосредственно из вашего кода (маршруты, подсказки типов, модели Pydantic, docstrings), она всегда **остаётся в синхронизации** с фактической реализацией — устраняя хроническую проблему устаревания документации, которая преследует рукописную документацию.

Интерактивный Swagger UI (`/docs`) позволяет разработчикам и потребителям API исследовать и **тестировать endpoints в реальном времени в браузере**, что значительно улучшает опыт разработчика и снижает трение при интеграции.

Генерируемая схема OpenAPI также может использоваться для создания клиентских SDK и тестирования контракта.

Получение профессиональной, точной, интерактивной документации API практически бесплатно — просто написав хорошо типизированный код — это значительное повышение производительности и качества, что делает это важной и отличительной возможностью FastAPI.