10 KiB
Додаткова конфігурація операцій шляху
OpenAPI operationId
/// warning | Попередження
Якщо ви не «експерт» з OpenAPI, імовірно, вам це не потрібно.
///
Ви можете встановити OpenAPI operationId, який буде використано у вашій операції шляху, за допомогою параметра operation_id.
Потрібно переконатися, що він унікальний для кожної операції.
{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py310.py hl[6] *}
Використання назви функції операції шляху як operationId
Якщо ви хочете використовувати назви функцій ваших API як operationId, ви можете пройтися по всіх них і переписати operation_id кожної операції шляху, використовуючи їхній APIRoute.name.
Зробіть це після додавання всіх операцій шляху.
{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *}
/// tip | Порада
Якщо ви вручну викликаєте app.openapi(), оновіть значення operationId до цього.
///
/// warning | Попередження
Якщо ви робите це, переконайтеся, що кожна з ваших функцій операцій шляху має унікальну назву.
Навіть якщо вони в різних модулях (файлах Python).
///
Виключення з OpenAPI
Щоб виключити операцію шляху зі згенерованої Схеми OpenAPI (а отже, і з автоматичних систем документації), використайте параметр include_in_schema і встановіть його в False:
{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *}
Розширений опис із docstring
Ви можете обмежити кількість рядків із docstring функції операції шляху, що використовуються для OpenAPI.
Додавання \f (екранованого символу «form feed») змусить FastAPI обрізати вивід для OpenAPI в цій точці.
Це не з’явиться в документації, але інші інструменти (такі як Sphinx) зможуть використати решту.
{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *}
Додаткові відповіді
Ймовірно, ви вже бачили, як оголошувати response_model і status_code для операції шляху.
Це визначає метадані про основну відповідь операції шляху.
Також можна оголосити додаткові відповіді з їхніми моделями, кодами статусу тощо.
У документації є цілий розділ про це, ви можете прочитати його тут: Додаткові відповіді в OpenAPI{.internal-link target=_blank}.
Додатково в OpenAPI
Коли ви оголошуєте операцію шляху у своєму застосунку, FastAPI автоматично генерує відповідні метадані про цю операцію шляху для включення в Схему OpenAPI.
/// note | Технічні деталі
У специфікації OpenAPI це називається Об'єкт Operation.
///
Він містить усю інформацію про операцію шляху і використовується для побудови автоматичної документації.
Він включає tags, parameters, requestBody, responses тощо.
Цю OpenAPI-схему, специфічну для операції шляху, зазвичай генерує FastAPI автоматично, але ви також можете її розширити.
/// tip | Порада
Це низькорівнева точка розширення.
Якщо вам потрібно лише оголосити додаткові відповіді, зручніше зробити це через Додаткові відповіді в OpenAPI{.internal-link target=_blank}.
///
Ви можете розширити OpenAPI-схему для операції шляху, використовуючи параметр openapi_extra.
Розширення OpenAPI
openapi_extra може бути корисним, наприклад, для оголошення OpenAPI Extensions:
{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py310.py hl[6] *}
Якщо ви відкриєте автоматичну документацію API, ваше розширення з’явиться внизу конкретної операції шляху.
І якщо ви відкриєте згенерований OpenAPI (за адресою /openapi.json у вашому API), ви також побачите своє розширення як частину конкретної операції шляху:
{
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/items/": {
"get": {
"summary": "Read Items",
"operationId": "read_items_items__get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
},
"x-aperture-labs-portal": "blue"
}
}
}
}
Власна схема OpenAPI для операції шляху
Словник у openapi_extra буде глибоко об’єднано з автоматично згенерованою OpenAPI-схемою для операції шляху.
Тож ви можете додати додаткові дані до автоматично згенерованої схеми.
Наприклад, ви можете вирішити читати та перевіряти запит власним кодом, не використовуючи автоматичні можливості FastAPI з Pydantic, але все ж захотіти визначити запит у Схемі OpenAPI.
Ви можете зробити це за допомогою openapi_extra:
{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py310.py hl[19:36, 39:40] *}
У цьому прикладі ми не оголошували жодної моделі Pydantic. Насправді тіло запиту навіть не розібрано як JSON, воно читається безпосередньо як bytes, а функція magic_data_reader() відповідатиме за його розбір певним чином.
Водночас ми можемо оголосити очікувану схему для тіла запиту.
Власний тип вмісту OpenAPI
Використовуючи той самий прийом, ви можете застосувати модель Pydantic, щоб визначити Схему JSON, яка потім включається в користувацький розділ OpenAPI-схеми для операції шляху.
І ви можете зробити це, навіть якщо тип даних у запиті - не JSON.
Наприклад, у цьому застосунку ми не використовуємо вбудовану функціональність FastAPI для отримання Схеми JSON з моделей Pydantic і не використовуємо автоматичну валідацію для JSON. Насправді ми оголошуємо тип вмісту запиту як YAML, а не JSON:
{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[15:20, 22] *}
Попри те, що ми не використовуємо типову вбудовану функціональність, ми все одно використовуємо модель Pydantic, щоб вручну згенерувати Схему JSON для даних, які хочемо отримати у форматі YAML.
Потім ми працюємо із запитом безпосередньо і отримуємо тіло як bytes. Це означає, що FastAPI навіть не намагатиметься розібрати корисне навантаження запиту як JSON.
Далі у нашому коді ми безпосередньо розбираємо цей YAML-вміст і знову використовуємо ту саму модель Pydantic, щоб перевірити YAML-вміст:
{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[24:31] *}
/// tip | Порада
Тут ми перевикористовуємо ту саму модель Pydantic.
Але так само ми могли б перевіряти дані іншим способом.
///