python asyncio api async fastapi framework json json-schema openapi openapi3 pydantic python-types python3 redoc rest starlette swagger swagger-ui uvicorn web

12 KiB

Raw Blame History

Власні статичні ресурси для UI документації (самостійне хостингування)

Документація API використовує Swagger UI і ReDoc, і кожному з них потрібні деякі файли JavaScript і CSS.

За замовчуванням ці файли віддаються через CDN.

Але це можна налаштувати: ви можете вказати конкретний CDN або віддавати файли самостійно.

Власний CDN для JavaScript і CSS

Припустімо, ви хочете використовувати інший CDN, наприклад https://unpkg.com/.

Це може бути корисно, наприклад, якщо ви живете в країні, яка обмежує доступ до деяких URL.

Вимкнути автоматичну документацію

Перший крок — вимкнути автоматичну документацію, адже за замовчуванням вона використовує стандартний CDN.

Щоб вимкнути її, встановіть її URL у None під час створення застосунку FastAPI:

{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[8] *}

Додати власну документацію

Тепер ви можете створити операції шляху для власної документації.

Ви можете повторно використати внутрішні функції FastAPI для створення HTML-сторінок документації та передати їм потрібні аргументи:

openapi_url: URL, звідки HTML-сторінка документації може отримати схему OpenAPI для вашого API. Тут можна використати атрибут app.openapi_url.
title: заголовок вашого API.
oauth2_redirect_url: тут можна використати app.swagger_ui_oauth2_redirect_url, щоб застосувати значення за замовчуванням.
swagger_js_url: URL, звідки HTML для документації Swagger UI може отримати файл JavaScript. Це URL вашого власного CDN.
swagger_css_url: URL, звідки HTML для документації Swagger UI може отримати файл CSS. Це URL вашого власного CDN.

І так само для ReDoc...

{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[2:6,11:19,22:24,27:33] *}

/// tip | Порада

Операція шляху для swagger_ui_redirect — це допоміжний обробник для випадку, коли ви використовуєте OAuth2.

Якщо ви інтегруєте ваш API з OAuth2-провайдером, ви зможете пройти автентифікацію, повернутися до документації API з отриманими обліковими даними та взаємодіяти з ним, використовуючи справжню OAuth2-автентифікацію.

Swagger UI зробить це «за лаштунками» для вас, але для цього йому потрібен цей допоміжний «redirect».

///

Створити операцію шляху для перевірки

Тепер, щоб мати змогу перевірити, що все працює, створіть операцію шляху:

{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[36:38] *}

Перевірка

Тепер ви маєте змогу перейти до документації за адресою http://127.0.0.1:8000/docs і перезавантажити сторінку — вона завантажить ці ресурси з нового CDN.

Самостійне хостингування JavaScript і CSS для документації

Самостійне хостингування JavaScript і CSS може бути корисним, наприклад, якщо ваш застосунок має продовжувати працювати навіть офлайн — без доступу до відкритого Інтернету — або в локальній мережі.

Тут ви побачите, як віддавати ці файли самостійно, у тому ж застосунку FastAPI, і налаштувати документацію так, щоб вона їх використовувала.

Структура файлів проєкту

Припустімо, структура файлів вашого проєкту виглядає так:

.
├── app
│   ├── __init__.py
│   ├── main.py

Тепер створіть директорію для зберігання цих статичних файлів.

Нова структура файлів може виглядати так:

.
├── app
│   ├── __init__.py
│   ├── main.py
└── static/

Завантажити файли

Завантажте статичні файли, потрібні для документації, і покладіть їх у директорію static/.

Ймовірно, ви можете натиснути правою кнопкою миші на кожне посилання та вибрати щось на кшталт «Save link as...».

Swagger UI використовує файли:

А ReDoc використовує файл:

redoc.standalone.js

Після цього структура файлів може виглядати так:

.
├── app
│   ├── __init__.py
│   ├── main.py
└── static
    ├── redoc.standalone.js
    ├── swagger-ui-bundle.js
    └── swagger-ui.css

Віддавати статичні файли

Імпортуйте StaticFiles.
«Змонтуйте» екземпляр StaticFiles() на конкретному шляху.

{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[7,11] *}

Перевірити статичні файли

Запустіть ваш застосунок і перейдіть за адресою http://127.0.0.1:8000/static/redoc.standalone.js.

Ви маєте побачити дуже довгий JavaScript-файл для ReDoc.

Він може починатися приблизно так:

/*! For license information please see redoc.standalone.js.LICENSE.txt */
!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")):
...

Це підтверджує, що ви можете віддавати статичні файли зі свого застосунку і що ви розмістили статичні файли для документації в правильному місці.

Тепер ми можемо налаштувати застосунок так, щоб він використовував ці статичні файли для документації.

Вимкнути автоматичну документацію для статичних файлів

Так само, як і при використанні власного CDN, перший крок — вимкнути автоматичну документацію, адже за замовчуванням вона використовує CDN.

Щоб вимкнути її, встановіть її URL у None під час створення застосунку FastAPI:

{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[9] *}

Додати власну документацію для статичних файлів

І так само, як із власним CDN, тепер ви можете створити операції шляху для власної документації.

Знову ж таки, ви можете повторно використати внутрішні функції FastAPI для створення HTML-сторінок документації та передати їм потрібні аргументи:

openapi_url: URL, звідки HTML-сторінка документації може отримати схему OpenAPI для вашого API. Тут можна використати атрибут app.openapi_url.
title: заголовок вашого API.
oauth2_redirect_url: тут можна використати app.swagger_ui_oauth2_redirect_url, щоб застосувати значення за замовчуванням.
swagger_js_url: URL, звідки HTML для документації Swagger UI може отримати файл JavaScript. Тепер його віддає ваш власний застосунок.
swagger_css_url: URL, звідки HTML для документації Swagger UI може отримати файл CSS. Тепер його віддає ваш власний застосунок.