Как кастомизировать Swagger UI в Python веб-фреймворках?

Ответ

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/ с указанными заголовком и описанием.