Ответ
В 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"}Ответ 18+ 🔞
Да ты посмотри, что эти FastAPI-шники вытворяют! Ну, блядь, сидишь ты, пишешь свой API, а потом открываешь документацию — и там такая стандартная, серая, скучная страница, что аж тоска берёт. Так нет же, можно же её, сука, разукрасить, как ёлку на Новый год!
1. Метаданные — это как визитка, блядь
Ну, представь, заходишь ты в бар, а там на стойке табличка «Бар». И всё. Ни названия, ни описания, нихуя. Так и твой API. Чтобы не быть таким мудаком, надо сразу задать параметры.
from fastapi import FastAPI
app = FastAPI(
title="Мой Охуенный API",
description="Вот тут я описал, что этот API делает. Можно даже **жирным** писать, Markdown же поддерживается!",
version="2.5.0"
)Вот теперь вверху Swagger UI будет красивый заголовок и описание. Уже не стыдно ссылку коллеге скинуть.
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}Добавил тег tags=["Пользователи"] — и всё, этот эндпоинт теперь в группе «Пользователи». Кликнул на группу — и видишь только то, что нужно. Красота, ёпта!
3. Параметры Swagger UI — мелкие, но важные прибамбасы
А знаешь, что самое раздражающее? Когда открываешь документацию, а там все эндпоинты развёрнуты, и надо скроллить дохуя. Или когда не можешь быстро найти нужный метод. Так вот, это лечится.
app = FastAPI(
swagger_ui_parameters={
"docExpansion": "none", # "list" (по умолчанию), "full", "none"
"filter": True, # Включает строку поиска для фильтрации по тегам
"persistAuthorization": True, # Сохраняет токен авторизации между перезагрузками
}
)Поставил "docExpansion": "none" — и все эндпоинты свёрнуты. Хочешь посмотреть один — разверни его. "filter": True — сверху появится строка поиска. Ввёл «user» — и видишь только эндпоинты с этим словом. Просто волшебство, блядь!
4. Авторизация — чтобы не копировать токен вручную, как последний лузер
Твой API под защитой, нужен токен. И что, каждый раз его из Postman тащить? Да ну нахуй. В Swagger UI есть кнопочка «Authorize»!
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"}Добавил зависимость Depends(security). Теперь в документации сверху справа появится заветная кнопка. Нажал на неё, вставил свой токен (например, Bearer eyJhbGciOi...) — и всё, можно тестировать защищённые ручки прямо из браузера. Удобно, сука, до невозможности!
Вот так, с помощью этих нехитрых приёмов, можно превратить свою документацию из унылого говна в конфетку. Главное — не лениться, блядь.