Модуль 12 · Урок 44 із 58
FastAPI і ASGI: path operations, parameters та OpenAPI
FastAPI не скасовує HTTP contract — він перетворює Python type hints і path operation declarations на перевірний ASGI application, runtime validation та OpenAPI. Хороший endpoint починається не з декоратора, а з чіткої resource semantics.
Безпечна FastAPI-практика модуля 12
Пакет містить synthetic SprintBoard API, Pydantic v2 models, dependencies, Problem Details, middleware, TestClient і OpenAPI contract tests. Він не відкриває зовнішню мережу під час tests, не містить authentication substitutes, персональних чи production-даних, credentials або production endpoints.
ASGI відділяє application від server
FastAPI application є ASGI callable. Uvicorn або інший ASGI server приймає network connection, формує ASGI events і викликає application; framework маршрутизує request до path operation. Завдяки цьому application можна тестувати in-process без відкриття зовнішнього port.
Development server з auto-reload зручний локально, але не є production design. Bind address, workers, proxy headers, timeouts і graceful shutdown визначаються окремим deployment contract.
Path operation поєднує path, method і function
Декоратор @app.get("/tasks/{task_id}") реєструє GET operation, а function описує параметри та результат. URL називає resource, method передає intent, а status_code, response_model, responses, tags і summary документують contract.
from fastapi import FastAPI, Query, status
from typing import Annotated
app = FastAPI(title="SprintBoard API", version="1.0.0")
@app.get("/tasks/{task_id}", operation_id="get_task")
async def get_task(task_id: int, verbose: bool = False):
return {"id": task_id, "verbose": verbose}
@app.get("/tasks", operation_id="list_tasks")
async def list_tasks(limit: Annotated[int, Query(ge=1, le=50)] = 20):
return {"items": [], "limit": limit}Explicit operation_id має бути унікальним і стабільним, якщо OpenAPI використовують для client generation або contract comparison.
Джерело параметра визначається декларацією
Ім’я, присутнє у path template, стає path parameter. Простий scalar зазвичай читається з query. Pydantic model без іншого marker інтерпретується як JSON request body. Header, Cookie, Form, File і Body задають інші transport locations.
| Declaration | Source | Failure example |
|---|---|---|
task_id: int у path | /tasks/{task_id} | Невалідний integer → 422 |
limit: Query(ge=1) | ?limit=20 | 0 порушує boundary |
payload: TaskCreate | JSON body | Missing field або wrong type |
x_request_id: Header() | HTTP field | Required header відсутній |
GET body технічно може підтримуватися framework, але має неоднозначну interoperability semantics і не є звичайним способом передати filter.
OpenAPI — результат contract declarations
FastAPI генерує /openapi.json, Swagger UI та ReDoc із routes, parameters, request bodies, responses і JSON Schemas. Це не заміна review: automatic schema не знає вашої domain authorization, idempotency, rate limits, data retention або side effects.
Docs must match runtime
Тест перевіряє не тільки HTML docs, а й OpenAPI operation, required fields, status codes та реальний response. Якщо handler повертає інший shape, contract вважається зламаним.
Local run має чітку boundary
Для навчання server запускають на 127.0.0.1, використовують synthetic fixtures і не підключають production database, credentials чи зовнішні APIs. 0.0.0.0 відкриває listener на всіх interfaces і потребує усвідомленого network policy.
- Назвіть resource та operations.
- Розкладіть inputs за path, query, headers і body.
- Зафіксуйте success та failure responses.
- Перевірте OpenAPI й runtime одним тестом.
- Лише після цього обирайте deployment topology.
Методичні джерела
Урок, сценарії, пояснення й вправи створені SEOWORK. Посилання ведуть на офіційну документацію framework та стандартів.
Закріпіть матеріал уроку
Три сценарні питання. Для зарахування уроку потрібно дати щонайменше дві правильні відповіді.