Ответ
В FastAPI интерфейс Swagger UI можно кастомизировать несколькими способами для улучшения документации и удобства использования.
1. Изменение метаданных OpenAPI
Это базовый способ, позволяющий задать заголовок, описание и версию API, которые отображаются вверху страницы документации.
from fastapi import FastAPI
app = FastAPI(
title="My Awesome API",
description="Это описание моего API. Поддерживает Markdown.",
version="2.5.0"
)2. Группировка эндпоинтов с помощью тегов
Теги позволяют логически сгруппировать эндпоинты, что делает навигацию по документации значительно проще.
@app.get("/users/me", tags=["Пользователи"])
async def read_current_user():
return {"user_id": "current"}
@app.get("/items/{item_id}", tags=["Товары"])
async def read_item(item_id: int):
return {"item_id": item_id}3. Настройка параметров отображения Swagger UI
Можно управлять поведением самого интерфейса, например, сворачивать все эндпоинты по умолчанию или включить фильтрацию.
app = FastAPI(
swagger_ui_parameters={
"docExpansion": "none", # "list" (по умолчанию), "full", "none"
"filter": True, # Включает строку поиска для фильтрации по тегам
"persistAuthorization": True, # Сохраняет токен авторизации между перезагрузками
}
)4. Добавление схем безопасности (Авторизация)
Для защищенных эндпоинтов можно добавить кнопку Authorize, чтобы пользователи могли вводить токен (например, JWT) и тестировать их прямо из документации.
from fastapi.security import HTTPBearer
from fastapi import Depends, FastAPI
app = FastAPI()
security = HTTPBearer()
@app.get("/secure-data", dependencies=[Depends(security)])
async def get_secure_data():
return {"message": "This is secure data"}