12 KiB

Raw Blame History

Користувацькі статичні ресурси інтерфейсу документації (самохостинг)

Документація 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_py310.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_py310.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_py310.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/.

Ви, ймовірно, можете натиснути правою кнопкою на кожному посиланні і вибрати опцію на кшталт «Зберегти посилання як...».

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_py310.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_py310.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. Це той файл, який тепер віддає ваш власний застосунок.