Поки ви явно не вкажете інший тип медіа в параметрі `responses`, FastAPI вважатиме, що відповідь має той самий тип медіа, що й основний клас відповіді (типово `application/json`).
Усе це може здаватися надуманим. І поки що може бути не дуже зрозуміло, навіщо це корисно.
@ -66,7 +66,7 @@ checker(q="somequery")
## Залежності з `yield`, `HTTPException`, `except` та фоновими задачами { #dependencies-with-yield-httpexception-except-and-background-tasks }
/// warning | Попередження
/// warning
Найімовірніше, вам не знадобляться ці технічні деталі.
@ -98,7 +98,7 @@ checker(q="somequery")
Цю поведінку змінено у 0.118.0: завершальний код після `yield` знову виконується після відправлення відповіді.
/// info | Інформація
/// note
Як побачите нижче, це дуже схоже на поведінку до версії 0.106.0, але з кількома покращеннями та виправленнями помилок у крайових випадках.
@ -150,7 +150,7 @@ checker(q="somequery")
У **FastAPI** 0.106.0 це змінено, щоб не утримувати ресурси під час очікування, поки відповідь піде мережею.
/// tip | Порада
/// tip
Крім того, фонова задача зазвичай є незалежним набором логіки, який слід обробляти окремо, з власними ресурсами (наприклад, власним з'єднанням з базою даних).
Тут функція-обробник події `shutdown` запише текстовий рядок `"Application shutdown"` у файл `log.txt`.
/// info | Інформація
/// note | Примітка
У функції `open()` параметр `mode="a"` означає «append», тож рядок буде додано після всього, що є у файлі, без перезапису попереднього вмісту.
@ -152,7 +152,7 @@ async with lifespan(app):
Під капотом, у технічній специфікації ASGI, це частина [Протоколу тривалості життя](https://asgi.readthedocs.io/en/latest/specs/lifespan.html), і там визначені події `startup` і `shutdown`.
/// info | Інформація
/// note | Примітка
Ви можете прочитати більше про обробники `lifespan` у [документації Starlette про Lifespan](https://www.starlette.dev/lifespan/).
Деякі з цих рішень також можуть бути з відкритим кодом або мати безкоштовні тарифи, тож ви можете спробувати їх без фінансових зобов'язань. Інші комерційні генератори SDK також доступні й їх можна знайти онлайн. 🤓
На цьому етапі ви маєте потрібні операції шляху зворотного виклику (ті, які має реалізувати *зовнішній розробник* у *зовнішньому API*) у створеному вище маршрутизаторі зворотного виклику.
Тепер використайте параметр `callbacks` у декораторі операції шляху вашого API, щоб передати атрибут `.routes`(це насправді просто `list` маршрутів/операцій шляху) з цього маршрутизатора зворотного виклику:
Тепер використайте параметр `callbacks` у декораторі операції шляху вашого API, щоб передати атрибут `.routes` з цього маршрутизатора зворотного виклику:
Зверніть увагу, що ви передаєте не сам маршрутизатор (`invoices_callback_router`) у `callback=`, а атрибут`.routes`, тобто `invoices_callback_router.routes`.
Зверніть увагу, що ви передаєте не сам маршрутизатор (`invoices_callback_router`) у `callbacks=`, а його`.routes`, тобто `invoices_callback_router.routes`. FastAPI використає ці маршрути, щоб згенерувати документацію OpenAPI для зворотних викликів.
Це значно спростить для ваших користувачів **реалізацію їхніх API** для отримання ваших запитів **вебхуків**; вони навіть зможуть згенерувати частину власного коду API автоматично.
/// info | Інформація
/// note | Примітка
Вебхуки доступні в OpenAPI 3.1.0 і вище, підтримуються FastAPI `0.99.0` і вище.
@ -36,7 +36,7 @@
Визначені вами вебхуки потраплять до **схеми OpenAPI** та автоматичного **інтерфейсу документації**.
/// info | Інформація
/// note | Примітка
Об'єкт `app.webhooks` насправді є просто `APIRouter` - тим самим типом, який ви використовуєте, структуризуючи застосунок у кількох файлах.
### Використання назви *функції операції шляху* як operationId { #using-the-path-operation-function-name-as-the-operationid }
Якщо ви хочете використовувати назви функцій ваших API як `operationId`, ви можете пройтися по всіх них і переписати `operation_id` кожної *операції шляху*, використовуючи їхній `APIRoute.name`.
Якщо ви хочете використовувати назви функцій ваших API як `operationId`, ви можете передати власну `generate_unique_id_function` до `FastAPI`.
Зробіть це після додавання всіх *операцій шляху*.
Функція отримує кожен `APIRoute` і повертає `operationId`, який слід використовувати для цієї операції шляху.
Використовуючи фронтенд, ви можете змушувати AI-агента виконувати дії від вашого імені.
Оскільки він працює локально, а не у відкритому інтернеті, ви вирішуєте не налаштовувати жодної автентифікації, просто покладаючись на доступ до локальної мережі.
Оскільки він працює **локально**, а не у відкритому інтернеті, ви вирішуєте **не налаштовувати жодної автентифікації**, просто покладаючись на доступ до локальної мережі.
Один із ваших користувачів може встановити його і запустити локально.
Docker та інші інструменти збирають ці образи контейнерів інкрементально, додаючи один шар поверх іншого, починаючи з верхньої частини `Dockerfile` і додаючи будь-які файли, створені кожною інструкцією в `Dockerfile`.
Docker та подібні інструменти також використовують внутрішній кеш під час збірки образу. Якщо файл не змінювався з моменту останньої збірки, тоді він повторно використає той самий шар, створений востаннє, замість копіювання файлу знову та створення нового шару з нуля.
Docker та подібні інструменти також використовують внутрішній кеш під час збірки образу. Якщо файл не змінювався з моменту останньої збірки, тоді він повторно використає той самий шар, створений востанє, замість копіювання файлу знову та створення нового шару з нуля.
Просте уникнення копіювання файлів не обов’язково суттєво покращує ситуацію, але оскільки для цього кроку використано кеш, він може використати кеш і для наступного кроку. Наприклад, він може використати кеш для інструкції, яка встановлює залежності:
@ -492,7 +492,7 @@ Traefik має інтеграції з Docker, Kubernetes та іншими, т
Наявність іншого менеджера процесів всередині контейнера (як це було б із кількома працівниками) лише додасть зайвої складності, яку, найімовірніше, ви вже вирішуєте на рівні кластера.
### Контейнери з кількома процесами та особливі випадки { #containers-with-multiple-processes-and-special-cases }
### Контейнери з кількоми процесами та особливі випадки { #containers-with-multiple-processes-and-special-cases }
Звісно, є особливі випадки, коли ви можете захотіти мати контейнер із кількома процесами-працівниками Uvicorn всередині.
Якщо у вас кілька контейнерів, імовірно кожен запускає один процес (наприклад, у кластері Kubernetes), тоді ви, ймовірно, захочете мати окремий контейнер, який виконає попередні кроки в одному контейнері, запустивши один процес, перед запуском реплікованих контейнерів-працівників.
/// info | Інформація
/// note | Примітка
Якщо ви використовуєте Kubernetes, це, ймовірно, буде [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/).
Ви можете розгорнути свій застосунок FastAPI на [FastAPI Cloud](https://fastapicloud.com) **однією командою**, приєднуйтесь до списку очікування, якщо ще ні. 🚀
## Вхід { #login }
Переконайтеся, що у вас вже є обліковий запис **FastAPI Cloud** (ми запросили вас зі списку очікування 😉).
Потім увійдіть:
<divclass="termy">
```console
$ fastapi login
You are logged in to FastAPI Cloud 🚀
```
</div>
## Розгортання { #deploy }
Тепер розгорніть свій застосунок **однією командою**:
Ви можете розгорнути свій застосунок FastAPI на [FastAPI Cloud](https://fastapicloud.com) лише **однією командою**. 🚀
<divclass="termy">
@ -36,6 +16,8 @@ Deploying to FastAPI Cloud...
</div>
CLI автоматично визначить ваш застосунок FastAPI та розгорне його у хмарі. Якщо ви не увійшли, ваш браузер відкриється, щоб завершити процес автентифікації.
Ось і все! Тепер ви можете отримати доступ до свого застосунку за цим URL. ✨
@ -56,13 +56,12 @@ FastAPI використовує стандарт для побудови Python
* [Hypercorn](https://hypercorn.readthedocs.io/): ASGI-сервер, сумісний з HTTP/2 і Trio, серед інших можливостей.
* [Daphne](https://github.com/django/daphne): ASGI-сервер, створений для Django Channels.
* [Granian](https://github.com/emmett-framework/granian): Rust HTTP-сервер для Python-застосунків.
* [NGINX Unit](https://unit.nginx.org/howto/fastapi/): NGINX Unit - легке й універсальне середовище виконання вебзастосунків.
## Серверна машина і серверна програма { #server-machine-and-server-program }
Є невелика деталь щодо назв, яку варто пам'ятати. 💡
Слово «**сервер**» зазвичай означає і віддалений/хмарний комп'ютер (фізична або віртуальна машина), і програму, що працює на цій машині (наприклад, Uvicorn).
Слово «сервер» зазвичай означає і віддалений/хмарний комп'ютер (фізична або віртуальна машина), і програму, що працює на цій машині (наприклад, Uvicorn).
Майте на увазі, що коли ви бачите слово «сервер» загалом, воно може стосуватися будь-якого з цих двох значень.
Тут я покажу, як використовувати Uvicorn із процесами-працівниками за допомогою команди `fastapi` або безпосередньо команди `uvicorn`.
/// info | Інформація
/// note | Примітка
Якщо ви використовуєте контейнери, наприклад з Docker або Kubernetes, я розповім про це більше в наступному розділі: [FastAPI у контейнерах - Docker](docker.md).
- `openapi_version`: Версія специфікації OpenAPI, що використовується. Типово остання: `3.1.0`.
- `summary`: Короткий підсумок API.
- `description`: Опис вашого API; може містити markdown і буде показаний у документації.
- `routes`: Список маршрутів, це кожна з зареєстрованих *операцій шляху*. Їх беруть з `app.routes`.
- `routes`: Маршрути із застосунку, взяті з `app.routes`. FastAPI використовує їх для збирання зареєстрованих *операцій шляху*, включно з тими, що з підключених роутерів.
/// info | Інформація
/// tip | Технічні деталі
`app.routes` - це нижчорівневе дерево маршрутів. Воно може містити кандидати маршрутів, які FastAPI внутрішньо використовує для підключених роутерів, а не лише кінцеві об'єкти `APIRoute`.
Ви все одно можете передати `app.routes` до `get_openapi()`. FastAPI обійде це дерево маршрутів, щоб зібрати фактичні операції шляху.
///
/// note | Примітка
Параметр `summary` доступний в OpenAPI 3.1.0 і вище, підтримується FastAPI 0.99.0 і вище.
# Окремі схеми OpenAPI для введення та виведення, чи ні { #separate-openapi-schemas-for-input-and-output-or-not }
Відколи вийшов **Pydantic v2**, згенерований OpenAPI став трохи точнішим і більш коректним, ніж раніше. 😎
Відколи вийшов **Pydantic v2**, згенерований OpenAPI став трохи точнішим і більш **коректним**, ніж раніше. 😎
Насправді подекуди буде навіть **дві схеми JSON** в OpenAPI для тієї самої моделі Pydantic: для введення та для виведення - залежно від наявності значень за замовчуванням.
@ -84,7 +84,7 @@
У такому разі ви можете вимкнути цю можливість у **FastAPI** параметром `separate_input_output_schemas=False`.
/// info | Інформація
/// note | Примітка
Підтримку `separate_input_output_schemas` додано у FastAPI `0.102.0`. 🤓
За бажання ви можете розгорнути ваш застосунок FastAPI у [FastAPI Cloud](https://fastapicloud.com), перейдіть і приєднайтеся до списку очікування, якщо ви ще цього не зробили. 🚀
Якщо у вас вже є обліковий запис **FastAPI Cloud** (ми запросили вас зі списку очікування 😉), ви можете розгорнути ваш застосунок однією командою.
За бажання ви можете розгорнути ваш застосунок FastAPI у [FastAPI Cloud](https://fastapicloud.com) однією командою. 🚀
<divclass="termy">
@ -510,6 +508,8 @@ Deploying to FastAPI Cloud...
</div>
CLI автоматично визначить ваш застосунок FastAPI і розгорне його в хмарі. Якщо ви не ввійшли в обліковий запис, ваш браузер відкриється для завершення процесу автентифікації.
Ось і все! Тепер ви можете отримати доступ до вашого застосунку за цією URL-адресою. ✨
`users.router` містить `APIRouter` у файлі `app/routers/users.py`.
FastAPI зберігає оригінальний `APIRouter` і його `APIRoute` активними після включення router'а до основного застосунку.
А `items.router` містить `APIRouter` у файлі `app/routers/items.py`.
Це означає, що користувацькі підкласи `APIRouter` і `APIRoute` і надалі братимуть участь після включення router'а.
///
@ -394,19 +394,11 @@ from .routers.users import router
Це включить усі маршрути з цього router'а як частину застосунку.
/// note | Технічні деталі
Фактично, всередині для кожної *операції шляху*, оголошеної в `APIRouter`, буде створена окрема *операція шляху*.
Тобто за лаштунками все працюватиме так, ніби це один і той самий застосунок.
///
/// tip | Порада
Вам не потрібно перейматися продуктивністю під час включення router'ів.
Це займе мікросекунди і відбуватиметься лише під час запуску.
Це спроєктовано як легковагове рішення і не додає накладних витрат до кожного запиту.
Тож це не вплине на продуктивність. ⚡
@ -461,7 +453,7 @@ from .routers.users import router
Це тому, що ми хочемо включати їхні *операції шляху* в схему OpenAPI та інтерфейси користувача.
Оскільки ми не можемо просто ізолювати їх і «змонтувати» незалежно від решти, *операції шляху* «клонуються» (створюються заново), а не включаються безпосередньо.
FastAPI зберігає оригінальні router'и та операції шляху активними й поєднує префікси router'ів, залежності, мітки, відповіді та інші метадані під час обробки запитів і генерації OpenAPI.
///
@ -532,4 +524,16 @@ $ fastapi dev
router.include_router(other_router)
```
Переконайтеся, що ви робите це до включення `router` в застосунок `FastAPI`, щоб *операції шляху* з `other_router` також були включені.
Ви можете зробити це до або після включення `router` у застосунок `FastAPI`. FastAPI все одно включить *операції шляху* з `other_router` у маршрутизацію та OpenAPI.
Те саме стосується *операцій шляху*, доданих пізніше до router'ів. Вони також будуть видимі через попереднє включення.
/// warning | Технічні деталі
Уникайте прямої мутації `router.routes` після включення router'а. FastAPI розглядає включення router'а як «живе», тому оригінальний router і його маршрути залишаються частиною маршрутизації та генерації OpenAPI.
Використовуйте задокументовані API, такі як декоратори *операцій шляху* і `.include_router()`, щоб додавати маршрути та router'и.
Сприймайте `router.routes` як нижчорівневе дерево маршрутів, яке може містити визначення маршрутів і включені router'и, і уникайте покладатися на нього як на плаский список кінцевих *операцій шляху*.
`Body` також має всі ті самі додаткові параметри валідації та метаданих, що й `Query`, `Path` та інші, які ви побачите пізніше.
@ -126,7 +126,7 @@ q: str | None = None
Але якщо ви хочете, щоб він очікував JSON з ключем `item`, а всередині нього - вміст моделі, як це відбувається, коли ви оголошуєте додаткові параметри тіла, ви можете використати спеціальний параметр `Body` - `embed`:
Майте на увазі, що оскільки **браузери обробляють cookies** особливим чином і «за лаштунками», вони **не** дозволяють **JavaScript** легко з ними працювати.
Якщо ви зайдете до **інтерфейсу документації API** за адресою `/docs`, ви зможете побачити **документацію** для cookies у ваших *операціях шляху*.
Але навіть якщо ви заповните дані й натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookies не будуть відправлені, і ви побачите **помилку**, ніби ви не ввели жодних значень.
Але навіть якщо ви **заповните дані** й натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookies не будуть відправлені, і ви побачите **помилку**, ніби ви не ввели жодних значень.
///
@ -73,4 +73,4 @@
## Підсумок { #summary }
Ви можете використовувати **Pydantic-моделі** для оголошення <dfntitle="Візьміть останнє печиво перед тим, як підете. 🍪">**cookies**</dfn> у **FastAPI**. 😎
Ви можете використовувати **Pydantic-моделі** для оголошення <dfntitle="Візьміть останнє печиво перед тим, як підете. 🍪">**кукі**</dfn> у **FastAPI**. 😎
Для визначення кукі ви маєте використовувати `Cookie`, тому що в іншому випадку параметри будуть інтерпретовані як параметри запиту.
///
/// info
/// note
Майте на увазі, що оскільки **браузери обробляють кукі** спеціальним чином і за лаштунками, вони **не** дозволяють **JavaScript** легко взаємодіяти з ними.
Залежності продовжать працювати як очікується, і **найкраще** те, що **інформація про типи буде збережена**, а це означає, що ваш редактор зможе й надалі надавати **автозаповнення**, **помилки в рядку** тощо. Те саме і для інших інструментів, як-от `mypy`.
Це буде особливо корисно у **великій кодовій базі**, де ви використовуєте **одні й ті самі залежності** знову і знову в **багатьох *операціях шляху***.
Це буде особливо корисно у **великій кодовій базі**, де ви використовуєте **одні й ті ж залежності** знову і знову в **багатьох *операціях шляху***.
## Бути `async` чи не бути `async` { #to-async-or-not-to-async }
## Використання тієї ж залежності кілька разів { #using-the-same-dependency-multiple-times }
Якщо одна з ваших залежностей оголошена кілька разів для однієї операції шляху, наприклад, кілька залежностей мають спільну підзалежність, FastAPI знатиме, що цю підзалежність потрібно викликати лише один раз на запит.
Якщо одна з ваших залежностей оголошена кілька разів для однієї операції шляху, наприклад, кілька залежностей мають спільну підзалежність, **FastAPI** знатиме, що цю підзалежність потрібно викликати лише один раз на запит.
І він збереже повернуте значення у <dfntitle="Утиліта/система для збереження обчислених/згенерованих значень, щоб повторно використовувати їх замість повторного обчислення.">«кеш»</dfn> і передасть його всім «dependants», яким воно потрібне в цьому конкретному запиті, замість того щоб викликати залежність кілька разів для одного й того ж запиту.
### `fastapi dev` із шляхом { #fastapi-dev-with-path }
### `fastapi dev` із шляхом або з параметром CLI `--entrypoint`{ #fastapi-dev-with-path-or-with-entrypoint-cli-option }
Ви також можете передати шлях до файлу в команду `fastapi dev`, і вона вгадає обʼєкт FastAPI app, який слід використовувати:
@ -188,29 +188,19 @@ from backend.main import app
$ fastapi dev main.py
```
Але вам доведеться щоразу памʼятати передавати правильний шлях під час виклику команди `fastapi`.
Крім того, інші інструменти можуть не знайти його, наприклад [Розширення VS Code](../editor-support.md) або [FastAPI Cloud](https://fastapicloud.com), тому рекомендується використовувати `entrypoint` у `pyproject.toml`.
За бажанням ви можете розгорнути ваш FastAPI-застосунок у [FastAPI Cloud](https://fastapicloud.com), перейдіть і приєднайтеся до списку очікування, якщо ви цього ще не зробили. 🚀
Якщо у вас вже є обліковий запис **FastAPI Cloud** (ми запросили вас зі списку очікування 😉), ви можете розгорнути ваш застосунок однією командою.
Перед розгортанням переконайтеся, що ви увійшли:
<divclass="termy">
Або ви також можете передати параметр `--entrypoint` команді `fastapi dev`:
```console
$ fastapi login
You are logged in to FastAPI Cloud 🚀
$ fastapi dev --entrypoint main:app
```
</div>
Але вам доведеться щоразу памʼятати передавати правильний шлях\entrypoint під час виклику команди `fastapi`.
Крім того, інші інструменти можуть не знайти його, наприклад [Розширення VS Code](../editor-support.md) або [FastAPI Cloud](https://fastapicloud.com), тому рекомендується використовувати `entrypoint` у `pyproject.toml`.
За бажанням ви можете розгорнути ваш FastAPI-застосунок у [FastAPI Cloud](https://fastapicloud.com) однією командою. 🚀
<divclass="termy">
@ -226,6 +216,8 @@ Deploying to FastAPI Cloud...
</div>
CLI автоматично визначить ваш застосунок FastAPI і розгорне його в хмарі. Якщо ви не ввійшли, ваш браузер відкриється для завершення процесу автентифікації.
Ось і все! Тепер ви можете отримати доступ до вашого застосунку за цим URL. ✨
## Підібʼємо підсумки, крок за кроком { #recap-step-by-step }
@ -270,7 +262,7 @@ https://example.com/items/foo
/items/foo
```
/// info
/// note | Примітка
«Шлях» також зазвичай називають «ендпоінтом» або «маршрутом».
@ -322,7 +314,7 @@ https://example.com/items/foo
* шляху `/`
* використовуючи <dfntitle="HTTP метод GET"><code>get</code> операція</dfn>
/// info | `@decorator` Інформація
/// note | `@decorator` Інформація
Синтаксис `@something` у Python називається «декоратором».
@ -349,7 +341,7 @@ https://example.com/items/foo
* `@app.patch()`
* `@app.trace()`
/// tip
/// tip | Порада
Ви можете використовувати кожну операцію (HTTP-метод) як забажаєте.
# Метадані та URL-адреси документації { #metadata-and-docs-urls }
Ви можете налаштувати кілька конфігурацій метаданих у Вашому додатку **FastAPI**.
Ви можете налаштувати кілька конфігурацій метаданих у вашому додатку **FastAPI**.
## Метадані для API { #metadata-for-api }
@ -11,7 +11,7 @@
| `title` | `str` | Назва API. |
| `summary` | `str` | Короткий підсумок API. <small>Доступно з OpenAPI 3.1.0, FastAPI 0.99.0.</small> |
| `description` | `str` | Короткий опис API. Може використовувати Markdown. |
| `version` | `string` | Версія API. Це версія Вашого додатка, а не OpenAPI. Наприклад, `2.5.0`. |
| `version` | `string` | Версія API. Це версія вашого додатка, а не OpenAPI. Наприклад, `2.5.0`. |
| `terms_of_service` | `str` | URL до умов використання API. Якщо вказано, має бути у форматі URL. |
| `contact` | `dict` | Інформація для контакту з опублікованим API. Може містити кілька полів. <details><summary><code>contact</code> поля</summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Опис</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>Ідентифікаційне ім'я контактної особи або організації.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL, що вказує на контактну інформацію. <strong>МАЄ</strong> бути у форматі URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>Адреса електронної пошти контактної особи або організації. <strong>МАЄ</strong> бути у форматі адреси електронної пошти.</td></tr></tbody></table></details> |
| `license_info` | `dict` | Інформація про ліцензію для опублікованого API. Може містити кілька полів. <details><summary><code>license_info</code> поля</summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Опис</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>ОБОВ'ЯЗКОВО</strong> (якщо встановлено <code>license_info</code>). Назва ліцензії для API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>Ліцензійний вираз за [SPDX](https://spdx.org/licenses/) для API. Поле <code>identifier</code> взаємовиключне з полем <code>url</code>. <small>Доступно з OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL до ліцензії, яка використовується для API. <strong>МАЄ</strong> бути у форматі URL.</td></tr></tbody></table></details> |
@ -32,7 +32,7 @@
## Ідентифікатор ліцензії { #license-identifier }
З початку використання OpenAPI 3.1.0 та FastAPI 0.99.0 Ви також можете налаштувати `license_info` за допомогою `identifier` замість `url`.
З початку використання OpenAPI 3.1.0 та FastAPI 0.99.0 ви також можете налаштувати `license_info` за допомогою `identifier` замість `url`.
Наприклад:
@ -46,7 +46,7 @@
Кожен словник може містити:
* `name` (**обов'язково**): `str` з тією ж назвою тегу, яку Ви використовуєте у параметрі `tags` у Ваших *операціях шляху* та `APIRouter`s.
* `name` (**обов'язково**): `str` з тією ж назвою тегу, яку ви використовуєте у параметрі `tags` у ваших *операціях шляху* та `APIRouter`s.
* `description`: `str` з коротким описом тегу. Може містити Markdown і буде показано в інтерфейсі документації.
* `externalDocs`: `dict`, який описує зовнішню документацію з такими полями:
* `description`: `str` з коротким описом зовнішньої документації.
@ -64,7 +64,7 @@
/// tip | Порада
Вам не потрібно додавати метадані для всіх тегів, які Ви використовуєте.
Вам не потрібно додавати метадані для всіх тегів, які ви використовуєте.
Якщо Ви хочете повністю вимкнути схему OpenAPI, Ви можете встановити `openapi_url=None`, це також вимкне інтерфейси документації, які її використовують.
Якщо ви хочете повністю вимкнути схему OpenAPI, ви можете встановити `openapi_url=None`, це також вимкне інтерфейси документації, які її використовують.
У цьому випадку параметр функції `q` буде необов’язковим і за замовчуванням матиме значення `None`.
/// check | Перевірте
/// tip | Порада
Також зверніть увагу, що **FastAPI** достатньо розумний, щоб визначити, що параметр шляху `item_id` є параметром шляху, а `q` — ні, отже, це параметр query.
У FastAPI ви можете використовувати **Pydantic-моделі** для оголошення **полів форми**.
/// info
/// note | Примітка
Щоб використовувати форми, спочатку встановіть [`python-multipart`](https://github.com/Kludex/python-multipart).
@ -14,7 +14,7 @@ $ pip install python-multipart
///
/// note
/// note | Примітка
Це підтримується, починаючи з FastAPI версії `0.113.0`. 🤓
@ -40,7 +40,7 @@ $ pip install python-multipart
У деяких особливих випадках (ймовірно, не дуже поширених) ви можете **обмежити** поля форми лише тими, які були оголошені в Pydantic-моделі. І **заборонити** будь-які **додаткові** поля.
/// note
/// note | Примітка
Це підтримується, починаючи з FastAPI версії `0.114.0`. 🤓
Наприклад, один зі способів використання специфікації OAuth2 (так званий «password flow») вимагає надсилати `username` та `password` як поля форми.
Наприклад, один зі способів використання специфікації OAuth2 (так званий «потік паролю») вимагає надсилати `username` та `password` як поля форми.
<dfntitle="специфікація">специфікація</dfn> вимагає, щоб ці поля мали точні назви `username` і `password` та надсилалися у вигляді полів форми, а не JSON.
З `Form` ви можете оголошувати ті ж конфігурації, що і з `Body` (та `Query`, `Path`, `Cookie`), включаючи валідацію, приклади, псевдоніми (наприклад, `user-name` замість `username`) тощо.
/// info | Інформація
/// note | Примітка
`Form` — це клас, який безпосередньо наслідується від `Body`.
Щоб використовувати `EmailStr`, спочатку встановіть [`email-validator`](https://github.com/JoshData/python-email-validator).
@ -182,7 +182,7 @@ FastAPI виконує кілька внутрішніх операцій з Pyd
### Повернути Response напряму { #return-a-response-directly }
Найпоширенішим випадком буде [повернення Response напряму, як пояснюється пізніше у розширеній документації](../advanced/response-directly.md).
Найпоширенішим випадком буде [повернення Response напряму, як пояснюється пізніше у просунутому посібнику користувача](../advanced/response-directly.md).
Параметр `status_code` приймає число з HTTP кодом статусу.
/// info | Інформація
/// note | Примітка
`status_code` також може, як альтернативу, приймати `IntEnum`, наприклад, Python [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus).
OpenAPI 3.1.0 (який використовується починаючи з FastAPI 0.99.0) додав підтримку `examples`, що є частиною стандарту **Схеми JSON**.
@ -155,7 +155,7 @@ OpenAPI також додала поля `example` і `examples` до інших
* `File()`
* `Form()`
/// info | Інформація
/// note | Примітка
Цей старий специфічний для OpenAPI параметр `examples` тепер називається `openapi_examples`, починаючи з FastAPI `0.103.0`.
@ -171,7 +171,7 @@ OpenAPI також додала поля `example` і `examples` до інших
Це нове поле `examples` у Схемі JSON - це **просто `list`** прикладів, а не `dict` з додатковими метаданими, як в інших місцях OpenAPI (описаних вище).
/// info | Інформація
/// note | Примітка
Навіть після релізу OpenAPI 3.1.0 з цією новою простішою інтеграцією зі Схемою JSON, протягом певного часу Swagger UI, інструмент, який надає автоматичну документацію, не підтримував OpenAPI 3.1.0 (тепер підтримує, починаючи з версії 5.0.0 🎉).
Пакет [`python-multipart`](https://github.com/Kludex/python-multipart) автоматично встановлюється з **FastAPI**, коли ви виконуєте команду `pip install "fastapi[standard]"`.
@ -60,7 +60,7 @@ $ fastapi dev
<imgsrc="/img/tutorial/security/image01.png">
/// check | Кнопка Authorize!
/// tip | Кнопка Authorize!
У вас уже є нова блискуча кнопка «Authorize».
@ -118,7 +118,7 @@ OAuth2 був спроєктований так, щоб backend або API мо
У цьому прикладі ми використаємо **OAuth2** з потоком **Password**, використовуючи токен **Bearer**. Це робиться за допомогою класу `OAuth2PasswordBearer`.
/// info | Інформація
/// note | Примітка
«Bearer»-токен - не єдиний варіант.
@ -148,7 +148,7 @@ OAuth2 був спроєктований так, щоб backend або API мо
Незабаром ми також створимо фактичну операцію шляху.
/// info | Інформація
/// note | Примітка
Якщо ви дуже строгий «Pythonista», вам може не подобатися стиль імені параметра `tokenUrl` замість `token_url`.
**FastAPI** знатиме, що може використати цю залежність, щоб визначити «схему безпеки» в схемі OpenAPI (і в автоматичній документації API).
/// info | Технічні деталі
/// note | Технічні деталі
**FastAPI** знатиме, що може використати клас `OAuth2PasswordBearer` (оголошений у залежності), щоб визначити схему безпеки в OpenAPI, тому що він наслідує `fastapi.security.oauth2.OAuth2`, який своєю чергою наслідує `fastapi.security.base.SecurityBase`.
Це подібно до [Потік JSON Lines](stream-json-lines.md), але використовує формат `text/event-stream`, який нативно підтримується браузерами через [API `EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
/// info | Інформація
/// note | Примітка
Додано у FastAPI 0.135.0.
@ -81,7 +81,7 @@ FastAPI подбає про коректне виконання, щоб воно
## Сирі дані { #raw-data }
Якщо потрібно надіслати дані **без** кодування в JSON, використовуйте `raw_data` замість `data`.
Якщо потрібно надіслати дані без кодування в JSON, використовуйте `raw_data` замість `data`.
Це корисно для надсилання попередньо відформатованого тексту, рядків логів або спеціальних значень <dfntitle="Значення, яке використовується для позначення особливої умови або стану">«значення-сторож»</dfn>, як-от `[DONE]`.
@ -103,7 +103,7 @@ FastAPI подбає про коректне виконання, щоб воно
## SSE з POST { #sse-with-post }
SSE працює з **будь-яким HTTP-методом**, не лише з `GET`.
SSE працює з будь-яким HTTP-методом, не лише з `GET`.
Це корисно для протоколів на кшталт [MCP](https://modelcontextprotocol.io), які транслюють SSE через `POST`:
@ -113,8 +113,8 @@ SSE працює з **будь-яким HTTP-методом**, не лише з
FastAPI реалізує деякі найкращі практики SSE «з коробки».
- Надсилати **коментар «keep alive» `ping`** кожні 15 секунд, коли не було жодного повідомлення, щоб запобігти закриттю з'єднання деякими проксі, як рекомендовано у [Специфікації HTML: Події, надіслані сервером](https://html.spec.whatwg.org/multipage/server-sent-events.html#authoring-notes).
- Встановити заголовок `Cache-Control: no-cache`, щоб **запобігти кешуванню** потоку.
- Встановити спеціальний заголовок `X-Accel-Buffering: no`, щоб **запобігти буферизації** у деяких проксі, наприклад Nginx.
- Надсилати коментар «keep alive» `ping` кожні 15 секунд, коли не було жодного повідомлення, щоб запобігти закриттю з'єднання деякими проксі, як рекомендовано у [Специфікації HTML: Події, надіслані сервером](https://html.spec.whatwg.org/multipage/server-sent-events.html#authoring-notes).
- Встановити заголовок `Cache-Control: no-cache`, щоб запобігти кешуванню потоку.
- Встановити спеціальний заголовок `X-Accel-Buffering: no`, щоб запобігти буферизації у деяких проксі, наприклад Nginx.
Вам не потрібно нічого з цим робити, воно працює «з коробки». 🤓
У вас може бути послідовність даних, яку ви хочете надсилати у **«потоці»**, це можна зробити за допомогою **JSON Lines**.
/// info | Інформація
/// note | Примітка
Додано в FastAPI 0.134.0.
@ -48,7 +48,7 @@ sequenceDiagram
Це дуже схоже на масив JSON (еквівалент списку Python), але замість того, щоб бути загорнутим у `[]` і мати `,` між елементами, тут є **по одному об’єкту JSON на рядок**, вони розділені символом нового рядка.
/// info | Інформація
/// note | Примітка
Важливо те, що ваш застосунок зможе по черзі створювати кожен рядок, поки клієнт споживає попередні рядки.
Sebastián Ramírez
2 days ago
GitHub