Swagger UI
и ReDoc

§1Два интерфейса поверх одного файла

Ни Swagger UI, ни ReDoc ничего не знают о вашем коде. Оба читают один и тот же openapi.json и рисуют его по-своему. Отсюда следует: если в интерфейсе чего-то не хватает, исправлять нужно описание, то есть код, из которого оно собрано.

§2Swagger UI: как устроен экран

Откройте http://127.0.0.1:8000/docs. Экран делится на три части: шапка с метаданными, список операций по группам и раздел схем внизу.

Внутри раскрытой операции у каждого ответа есть вкладки Example Value и Schema. Первая показывает готовый пример, вторая — правила: типы, ограничения, обязательные поля. Когда спорят, «что должно приходить», смотрят вторую.

§3Выполнить запрос из браузера

Главное отличие Swagger UI: запрос можно отправить, не выходя из страницы. Порядок один и тот же для любой операции.

1. Раскройте операцию — щелчок по её строке.
2. Нажмите «Try it out» — поля формы станут доступными для ввода.
3. Заполните параметры и тело. Тело подставляется из примера в схеме, его достаточно поправить.
4. Нажмите «Execute». Браузер отправит настоящий запрос на выбранный сервер.
5. Прочитайте ответ — код, тело, заголовки и готовая команда curl для повторения в терминале.

§4Авторизация в Swagger UI

Операции записи в учебном сервисе требуют токен. Swagger UI знает об этом из раздела security — рядом с такими операциями стоит значок замка, а в шапке есть кнопка Authorize.

Если запрос без токена — сервис ответит 401, если токен есть, но прав не хватает — 403. Разницу между этими кодами разбирали в главе 2.3; здесь важно, что оба ответа видно в том же окне, сразу после «Execute».

§5Что видно в ответе, кроме тела

Часть контракта передаётся не в теле, а в заголовках ответа. Swagger UI показывает их в блоке Response headers.

Устаревшие операции интерфейс тоже помечает: заголовок перечёркнут, рядом плашка deprecated. Это поле deprecated: true в описании — предупреждение читателю до того, как он начнёт писать код.

§6ReDoc: документация для чтения

Тот же контракт по адресу http://127.0.0.1:8000/redoc выглядит иначе: слева оглавление, в центре текст, справа примеры запросов и ответов.

ReDoc удобно показывать заказчику, аналитику или преподавателю: страница читается сверху вниз, и на ней нет кнопки, отправляющей запрос на рабочий сервер. Её же публикуют как статический сайт — в учебном проекте она собирается на GitHub Pages, и это отдельная глава модуля 7.

§7Как их подключают

FastAPI даёт оба интерфейса сразу, без установки: /docs и /redoc появляются вместе с приложением. Но в учебном проекте адрес /redoc задан вручную — и на это есть причина.

REDOC_JS_URL = "https://cdn.jsdelivr.net/npm/redoc@2.5.4/bundles/redoc.standalone.js"

app = FastAPI(…, redoc_url=None)

@app.get("/redoc", include_in_schema=False)
def redoc_html():
    return get_redoc_html(openapi_url=app.openapi_url, title=…, redoc_js_url=REDOC_JS_URL)

Встроенный вариант ссылается на адрес redoc@next, который у поставщика библиотеки возвращает 404 — страница открывалась пустой. Поэтому версия закреплена: redoc@2.5.4. Это общее правило работы с внешними адресами: закрепляйте версию, иначе ваша страница зависит от чужих изменений.

§8Что выбрать под задачу

Выбор между ними определяется задачей: изменить состояние сервиса или прочитать контракт.