Какие знаешь способы кастомизации интерфейса Swagger?

2.0 Middle🔥 71 комментариев

#Python Core

Комментарии (1)

🐱

claude-haiku-4.5PrepBro AI22 мар. 2026 г.(ред.)

Ответ сгенерирован нейросетью и может содержать ошибки

# Способы кастомизации интерфейса Swagger

Swagger (OpenAPI) предоставляет множество способов для кастомизации внешнего вида и поведения документации API. Рассмотрим основные подходы, которые используются в production-приложениях.

Кастомизация через параметры FastAPI

При инициализации приложения FastAPI можно передать параметры для настройки Swagger UI:

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="API description",
    version="1.0.0",
    docs_url="/api/docs",  # Кастомный URL для документации
    redoc_url="/api/redoc",  # Кастомный URL для ReDoc
    openapi_url="/api/openapi.json"  # Кастомный URL для OpenAPI схемы
)

Кастомизация HTML шаблона Swagger

Можно переопределить HTML шаблон, используемый для отображения Swagger UI:

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
from fastapi.staticfiles import StaticFiles

app = FastAPI()

def custom_swagger_ui_html():
    return """
    <!DOCTYPE html>
    <html>
      <head>
        <title>Custom Swagger UI</title>
        <meta charset="utf-8"/>
        <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css">
        <style>
          .swagger-ui { background-color: #f5f5f5; }
          .topbar { background-color: #2c3e50; }
        </style>
      </head>
      <body>
        <div id="swagger-ui"></div>
        <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>
          SwaggerUIBundle({
            url: "/openapi.json",
            dom_id: "#swagger-ui",
            presets: [
              SwaggerUIBundle.presets.apis,
              SwaggerUIBundle.SwaggerUIStandalonePreset
            ]
          })
        </script>
      </body>
    </html>
    """

app.swagger_ui_init_oauth = {}

Кастомизация OpenAPI схемы

Можно программно модифицировать OpenAPI схему перед её отправкой:

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    
    openapi_schema = get_openapi(
        title="Custom API",
        version="2.0.0",
        description="Кастомное описание API",
        routes=app.routes,
    )
    
    # Добавляем кастомные тэги
    openapi_schema["info"]["x-logo"] = {
        "url": "https://example.com/logo.png"
    }
    
    # Добавляем серверы
    openapi_schema["servers"] = [
        {"url": "https://api.example.com", "description": "Production"},
        {"url": "https://staging.example.com", "description": "Staging"}
    ]
    
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

Кастомизация через CSS и JavaScript

Можно добавлять CSS и JavaScript для изменения внешнего вида:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
import os

app = FastAPI()

# Подключаем статические файлы
app.mount("/static", StaticFiles(directory="static"), name="static")

def get_swagger_ui_html():
    return """
    <!DOCTYPE html>
    <html>
      <head>
        <title>API Documentation</title>
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css">
        <link rel="stylesheet" href="/static/custom-swagger.css">
      </head>
      <body>
        <div id="swagger-ui"></div>
        <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script src="/static/custom-swagger.js"></script>
      </body>
    </html>
    """

Использование Swagger расширений (Extensions)

Swagger поддерживает расширения (x-* поля) для добавления пользовательских данных:

from fastapi import FastAPI
from pydantic import BaseModel

class CustomSchema(BaseModel):
    name: str
    
    class Config:
        json_schema_extra = {
            "example": {
                "name": "John Doe"
            },
            "x-custom-field": "custom-value"
        }

Управление видимостью endpoints

Можно исключить определённые endpoints из документации:

from fastapi import FastAPI

app = FastAPI()

@app.get("/public", tags=["Public"])
async def public_endpoint():
    return {"message": "This is public"}

@app.get("/internal", include_in_schema=False)  # Скрывается из документации
async def internal_endpoint():
    return {"message": "This is hidden"}

Группировка endpoints с помощью тэгов

Тэги помогают организовать endpoints в документации:

@app.get("/users", tags=["Users"])
async def get_users():
    return []

@app.post("/users", tags=["Users"])
async def create_user():
    return {}

@app.get("/posts", tags=["Posts"])
async def get_posts():
    return []

Поддержка OAuth и Security

Можно добавлять информацию о безопасности в Swagger:

from fastapi.security import HTTPBearer, HTTPAuthCredentials

security = HTTPBearer()

@app.get("/protected", security_scopes=security)
async def protected_endpoint(credentials: HTTPAuthCredentials):
    return {"token": credentials.credentials}

Заключение

Кастомизация Swagger — важный аспект разработки API. Основные способы включают:

Параметры FastAPI — быстрое переименование и настройка URL
Модификация OpenAPI схемы — добавление пользовательских данных
HTML/CSS/JS — полная кастомизация интерфейса
Расширения (extensions) — добавление нестандартных данных
Управление видимостью — контроль того, что попадает в документацию
Безопасность — интеграция с аутентификацией и авторизацией

Выбор подхода зависит от требований проекта и уровня необходимой кастомизации.