Skip to content

Глава 3.5: Автоматическая документация Swagger

Время изучения: 30 минут

1. Документация API: Инструкция по эксплуатации космической станции

Представьте, что вы новый астронавт, прибывший на МКС. Как вам узнать, какой тумблер за что отвечает и как управлять роботизированной рукой? Вам нужна подробная и актуальная инструкция.

Документация API — это такая же инструкция для разработчиков. Она объясняет:

  • Какие "стыковочные порты" (endpoints) доступны.
  • Какие "команды" (HTTP-методы) можно отправлять.
  • Какой "груз" (данные) нужно передавать.
  • Какую "телеметрию" (ответы) ожидать.

Проблема в том, что ручное написание документации — это долго, скучно и она почти всегда устаревает.

💡 Космическая аналогия:

Ручная документация — это бумажные чертежи, которые лежат в архиве и не обновляются после модернизации станции. Автоматическая документация FastAPI — это интерактивный дисплей в ЦУП, который обновляется в реальном времени после каждого изменения на станции.

2. Магия FastAPI: Как это работает?

FastAPI делает всю "грязную работу" за вас, основываясь на вашем же коде. Он сканирует:

  1. Маршруты: Все декораторы @app.get, @app.post и т.д.
  2. Параметры: Параметры пути (ship_id: int) и запроса.
  3. Модели Pydantic: Ваши "чертежи" (Spaceship, SpaceshipCreate).
  4. Строки документации (docstrings): Описания, которые вы пишете в тройных кавычках.

На основе этих данных FastAPI генерирует схему по стандарту OpenAPI (ранее известный как Swagger), а затем показывает ее через два красивых интерфейса.

3. Исследуем "дисплей ЦУП": Swagger UI

Swagger UI — это интерактивный интерфейс, который позволяет не только читать документацию, но и тестировать API прямо из браузера.

Откройте http://127.0.0.1:8000/docs

Вы увидите:

  • Список эндпоинтов: Сгруппированные по тегам (по умолчанию, по названию ресурса) и окрашенные в цвета HTTP-методов.
  • Описания: Тексты из ваших docstrings ("""...""") отображаются как описания эндпоинтов.
  • Параметры: Показывает, какие параметры (как ship_id) ожидает endpoint, их тип и обязательность.
  • Тело запроса (Request Body): Для POST и PUT показывает JSON-схему, сгенерированную из вашей Pydantic-модели (SpaceshipCreate).
  • Ответы (Responses): Показывает возможные статус-коды и схемы ответов, основанные на response_model.
  • Кнопка "Try it out": Позволяет заполнить параметры и отправить реальный запрос на ваш сервер.

4. Улучшаем документацию: Теги и описания

Давайте сделаем нашу документацию еще более профессиональной.

Шаг 1: Добавляем метаданные в FastAPI При создании app можно передать общую информацию о вашем API.

Измените строку app = FastAPI() в main.py: 

# main.py

app = FastAPI(
    title="Fleet Management API",
    description="API для управления флотом космических аппаратов.",
    version="1.0.0",
)
Теперь вверху вашей документации появятся заголовок и описание.

Шаг 2: Группируем эндпоинты с помощью тегов Вы можете добавить теги к каждому эндпоинту, чтобы сгруппировать их по смыслу.

Добавьте параметр tags в декораторы: 

# GET /spaceships
@app.get("/spaceships", response_model=List[Spaceship], tags=["Космические аппараты"])
# ...

# GET /spaceships/{ship_id}
@app.get("/spaceships/{ship_id}", response_model=Spaceship, tags=["Космические аппараты"])
# ...

# POST /spaceships
@app.post("/spaceships", response_model=Spaceship, status_code=201, tags=["Космические аппараты"])
# ...

# и так далее для PUT и DELETE
Теперь все ваши CRUD-операции будут аккуратно сгруппированы под заголовком "Космические аппараты".

5. Альтернативный вид: ReDoc

FastAPI предоставляет еще один интерфейс для документации "из коробки" — ReDoc. Он менее интерактивный, но часто считается более читаемым и отлично подходит для статичной документации.

Откройте http://127.0.0.1:8000/redoc

Вы увидите трехколоночный макет с навигацией, описаниями эндпоинтов и схемами данных. Это отличный способ предоставить документацию вашим "клиентам" (например, команде фронтенда).

Квиз для закрепления

1. FastAPI генерирует документацию на основе...

2. Какой стандарт лежит в основе авто-документации FastAPI?

3. По какому URL по умолчанию доступна интерактивная документация Swagger UI?

4. Параметр `tags` в декораторе `@app.get` используется для:

5. ReDoc — это...

🚀 Итог главы:

Вы увидели одну из самых мощных "суперспособностей" FastAPI — создание документации без каких-либо усилий.

  • 📖 Ваше API теперь имеет два вида актуальной документации: Swagger UI и ReDoc.
  • 🔬 Документация интерактивна и позволяет тестировать API на лету.
  • 🏷️ Вы научились улучшать ее с помощью метаданных и тегов.

Инструкция по эксплуатации готова и всегда актуальна! В финальной главе этого раздела мы научимся обрабатывать "космические аномалии" — ошибки и некорректные данные.

📌 Проверка:

  • Убедитесь, что по адресу http://127.0.0.1:8000/docs отображаются заголовок, описание и сгруппированные по тегам эндпоинты.
  • Проверьте, что в разделе "Schemas" видна ваша модель Spaceship.
  • Откройте http://127.0.0.1:8000/redoc и оцените альтернативный вид.

⚠️ Если изменения не отображаются:

  • Убедитесь, что вы сохранили файл main.py.
  • Проверьте, что сервер uvicorn запущен с флагом --reload и успешно перезагрузился.