Ответ
Swagger UI можно гибко настраивать в Python-фреймворках с помощью специализированных библиотек. Наиболее популярные решения — flasgger для Flask и drf-yasg / drf-spectacular для Django REST Framework.
Они позволяют изменять как метаданные API, так и внешний вид самой документации.
Основные возможности кастомизации:
- Метаданные: Заголовок (
title), версия (version), описание (description). - URL: Изменение пути к документации (например, с
/docsна/api/docs). - Авторизация: Добавление кнопок и схем авторизации (ApiKey, Bearer JWT).
- Внешний вид: Подключение кастомных CSS для изменения цветовой схемы и логотипа.
Пример для Flask с flasgger:
from flask import Flask
from flasgger import Swagger
app = Flask(__name__)
# Конфигурация для кастомизации Swagger
swagger_config = {
"headers": [],
"specs": [
{
"endpoint": 'apispec_1',
"route": '/apispec_1.json',
}
],
"static_url_path": "/flasgger_static",
"swagger_ui": True,
"specs_route": "/apidocs/", # Кастомный URL
"title": "My Custom API", # Кастомный заголовок
"version": "2.0.0",
"description": "Это описание моего кастомного API"
}
swagger = Swagger(app, config=swagger_config)
@app.route('/')
def index():
"""Это главная страница.
---
responses:
200:
description: Успешный ответ
"""
return "Hello, World!"
if __name__ == '__main__':
app.run(debug=True)После запуска документация будет доступна по адресу http://127.0.0.1:5000/apidocs/ с указанными заголовком и описанием.
Ответ 18+ 🔞
Ах ты ж, блядь, смотри-ка, Swagger UI! Ну, это ж как та собака Муму, только для API — вроде и полезная штука, а если не настроить, так и утопить в озере захочется, ёпта.
Так вот, в этих ваших Python-фреймворках его можно настраивать так, что мамка не горюй. Есть спец-библиотеки, которые как Герасим — здоровые, молчаливые, но если что, так впердолят такую кастомизацию, что охуеешь.
Основные плюшки, которые можно вытворять:
- Метаданные: Менять заголовок, версию, описание — ну, как табличку на двери перевесить, блядь.
- URL: Путь к документации поменять, чтоб не
/docs, а, допустим,/api/docs— типа спрятать от лишних глаз, хитрая жопа. - Авторизация: Кнопочки добавить для входа, схемы эти ваши ApiKey или Bearer JWT прикрутить — чтоб не всякий пиздопроебибна зашёл.
- Внешний вид: CSS свой подсунуть, цвета поменять, логотип воткнуть — чтоб не как у всех, падлы.
Смотри, как в Flask с flasgger это выглядит, блядь:
from flask import Flask
from flasgger import Swagger
app = Flask(__name__)
# А вот тут мы его, сука, конфигурируем
swagger_config = {
"headers": [],
"specs": [
{
"endpoint": 'apispec_1',
"route": '/apispec_1.json',
}
],
"static_url_path": "/flasgger_static",
"swagger_ui": True,
"specs_route": "/apidocs/", # Свой URL, чтоб не палиться
"title": "My Custom API", # Свой заголовок, овердохуищный
"version": "2.0.0",
"description": "Это описание моего кастомного API" # Ну и пояснительная записка, бля
}
swagger = Swagger(app, config=swagger_config)
@app.route('/')
def index():
"""Это главная страница.
---
responses:
200:
description: Успешный ответ
"""
return "Hello, World!"
if __name__ == '__main__':
app.run(debug=True)Запустишь это дело, и твоя документация будет торчать уже не где попало, а по адресу http://127.0.0.1:5000/apidocs/, да ещё и с твоим фирменным шильдиком. Красота, ёпта, а не жизнь. Главное — не перемудрить, а то получится как у того Герасима: хотел как лучше, а в итоге Муму утопил, блядь.