Розширення OpenAPI

У деяких випадках вам може знадобитися змінити згенеровану схему OpenAPI.

У цьому розділі ви побачите як це зробити.

Звичайний процес

Звичайний (типовий) процес такий.

Застосунок FastAPI (екземпляр) має метод .openapi(), який має повертати схему OpenAPI.

Під час створення об'єкта застосунку реєструється операція шляху для /openapi.json (або для того значення, яке ви встановили в openapi_url).

Вона просто повертає відповідь JSON з результатом методу .openapi() застосунку.

Типово метод .openapi() перевіряє властивість .openapi_schema, і якщо там вже є дані, повертає їх.

Якщо ні, він генерує їх за допомогою утилітарної функції fastapi.openapi.utils.get_openapi.

Функція get_openapi() приймає такі параметри:

title: Заголовок OpenAPI, показується в документації.
version: Версія вашого API, напр. 2.5.0.
openapi_version: Версія специфікації OpenAPI, що використовується. Типово остання: 3.1.0.
summary: Короткий підсумок API.
description: Опис вашого API; може містити markdown і буде показаний у документації.
routes: Маршрути із застосунку, взяті з app.routes. FastAPI використовує їх для збирання зареєстрованих операцій шляху, включно з тими, що з підключених роутерів.

/// tip | Технічні деталі

app.routes - це нижчорівневе дерево маршрутів. Воно може містити кандидати маршрутів, які FastAPI внутрішньо використовує для підключених роутерів, а не лише кінцеві об'єкти APIRoute.

Ви все одно можете передати app.routes до get_openapi(). FastAPI обійде це дерево маршрутів, щоб зібрати фактичні операції шляху.

///

/// note | Примітка

Параметр summary доступний в OpenAPI 3.1.0 і вище, підтримується FastAPI 0.99.0 і вище.

///

Переписування типових значень

Використовуючи наведене вище, ви можете скористатися тією ж утилітарною функцією для генерації схеми OpenAPI і переписати потрібні частини.

Наприклад, додаймо розширення OpenAPI ReDoc для додавання власного логотипа.

Звичайний FastAPI

Спочатку напишіть ваш застосунок FastAPI як зазвичай:

{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[1,4,7:9] *}

Згенерувати схему OpenAPI

Далі використайте ту ж утилітарну функцію для генерації схеми OpenAPI всередині функції custom_openapi():

{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[2,15:21] *}

Змінити схему OpenAPI

Тепер можна додати розширення ReDoc, додавши власний x-logo до «об'єкта» info у схемі OpenAPI:

{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[22:24] *}

Кешувати схему OpenAPI

Ви можете використовувати властивість .openapi_schema як «кеш» для збереження згенерованої схеми.

Так вашому застосунку не доведеться щоразу генерувати схему, коли користувач відкриває документацію вашого API.

Вона буде згенерована лише один раз, а потім та сама закешована схема використовуватиметься для наступних запитів.

{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[13:14,25:26] *}

Переписати метод

Тепер ви можете замінити метод .openapi() вашою новою функцією.

{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[29] *}

Перевірте

Коли ви перейдете за адресою http://127.0.0.1:8000/redoc, побачите, що використовується ваш власний логотип (у цьому прикладі логотип FastAPI):

5.4 KiB Raw Blame History