Перейти к содержанию

Генерация документации 📝#

Вы создали, протестировали и улучшили своё FastStream-приложение, добавив взаимодействие между сервисами и валидацию данных с Pydantic! 🎉 Теперь пора задокументировать его, чтобы другие разработчики (или вы сами в будущем) могли понять, как оно работает. FastStream автоматически генерирует документацию в формате AsyncAPI, которая описывает ваши очереди, формат сообщений и публикации. В этом разделе мы научимся создавать и просматривать эту документацию, уделяя внимание тому, как данные о публикации отображаются в AsyncAPI. Готовы сделать ваше приложение понятным для всех? Погнали! 🚀

Что такое AsyncAPI? 🤔#

AsyncAPI — это стандарт для документирования асинхронных API, таких как приложения, работающие с брокерами сообщений. Он похож на OpenAPI (для REST API), но создан специально для систем, использующих очереди и события. AsyncAPI-документация показывает:

  • Какие очереди использует ваше приложение 📬.
  • Как выглядят сообщения (например, структура JSON, заданная Pydantic) 📋.
  • Какие публикации выполняет приложение (например, в какие очереди отправляются сообщения) 📤.
  • Как другие системы могут подключиться к вашему приложению 🔗.

FastStream делает генерацию AsyncAPI-документации невероятно простой — буквально пара команд! 😎

Шаг 1: Генерация документации 📄#

FastStream предоставляет CLI-команды для создания документации. Мы будем работать с приложением из предыдущих разделов (app.py), которое использует очереди input-queue и output-queue и модель Pydantic UserMessage.

Убедитесь, что вы находитесь в папке faststream-tutorial и ваше виртуальное окружение активно. Выполните команду:

faststream docs gen app:app

Что происходит? 🔍

  • app:app указывает на модуль app.py и объект app (экземпляр FastStream).
  • Команда анализирует ваше приложение, включая подписчиков (@broker.subscriber), публикации (@broker.publisher) и модели Pydantic.
  • Результат сохраняется в файл asyncapi.json в текущей директории.

Откройте asyncapi.json в текстовом редакторе. Вы увидите JSON-структуру, описывающую:

  • Очереди input-queue и output-queue.
  • Формат сообщений (UserMessage с полями username и message).
  • Публикацию сообщений из input-queue в output-queue благодаря @broker.publisher.

Tip

Разница между broker.publish и @broker.publisher 📤

При использовании @broker.publisher для публикации сообщений FastStream автоматически включает информацию о публикации в AsyncAPI-документацию, описывая, в какие очереди отправляются сообщения (например, output-queue в нашем случае). Это делает документацию полной, показывая не только подписки, но и потоки данных. В то же время метод broker.publish не добавляет такие данные в документацию, так как он предназначен для более гибкой отправки сообщений без декларативного описания. Используйте @broker.publisher, если хотите, чтобы структура публикации была отражена в AsyncAPI.

Шаг 2: Просмотр документации 🌐#

JSON-файл полезен, но читать его неудобно. FastStream позволяет запустить веб-интерфейс для просмотра документации в красивом формате HTML. Выполните:

faststream docs serve app:app

Что происходит? 🔄

  • FastStream генерирует AsyncAPI-документацию и запускает локальный веб-сервер.
  • Сервер не использует broker.start() или broker.connect(), так как он только анализирует код приложения, а не подключается к RabbitMQ.

Откройте браузер и перейдите по адресу http://localhost:8000. Вы увидите интерактивную HTML-страницу, где:

  • Показаны очереди input-queue и output-queue 🗄️.
  • Описана структура сообщений (UserMessage с полями username и message) 📋.
  • Отображена публикация из input-queue в output-queue, включая связь между подписчиком и издателем.

Попробуйте кликнуть по очередям и сообщениям — это помогает понять, как ваше приложение взаимодействует с брокером! 😊

Шаг 3: Улучшение документации ✍️#

Чтобы документация была информативнее, мы добавили метаданные в приложение: заголовок, описание, докстринги и метаданные Pydantic. Откройте app.py и убедитесь, что код соответствует следующему:

from pydantic import BaseModel, Field
from faststream import FastStream, Logger
from faststream.rabbit import RabbitBroker


# Определяем структуру сообщения с метаданными
class UserMessage(BaseModel):
    username: str = Field(description="Имя пользователя", examples=["Alice"])
    message: str = Field(description="Текст сообщения", examples=["Hello"])


# Создаем брокер и приложение с метаданными
broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
app = FastStream(
    broker,
    title="User Message Processor",
    description="Приложение для обработки пользовательских сообщений",
)


# Подписываемся на очередь input-queue
@broker.subscriber("input-queue")
@broker.publisher("output-queue")
async def handle_message(data: UserMessage, logger: Logger) -> UserMessage:
    """
    Принимает сообщение из input-queue, логирует его и
    отправляет в output-queue с текстом в верхнем регистре.
    """
    logger.info(f"Получено: {data.username} сказал '{data.message}'")
    return UserMessage(username=data.username, message=data.message.upper())


# Подписываемся на очередь output-queue
@broker.subscriber("output-queue")
async def check_result(data: UserMessage, logger: Logger) -> None:
    """
    Логирует обработанное сообщение из output-queue.
    """
    logger.info(f"Промежуточный результат: {data.username} сказал '{data.message}'")

Что изменилось? 🔍

  • Pydantic Field: Поля username и message в UserMessage имеют description (например, “Имя пользователя”) и examples (например, "Alice"), которые отображаются в AsyncAPI как описания и примеры полей.
  • Параметры title и description: В FastStream заданы title="User Message Processor" и description="Приложение для обработки пользовательских сообщений", которые становятся заголовком и описанием в документации.
  • Докстринги: Функции handle_message и check_result имеют докстринги, описывающие их назначение. FastStream парсит докстринги подписчиков (@broker.subscriber) и включает их в AsyncAPI.
  • Публикация с @broker.publisher: Декоратор @broker.publisher("output-queue") в handle_message указывает, что обработанные сообщения публикуются в output-queue. Это отображается в AsyncAPI как связь между input-queue (подписка) и output-queue (публикация).

Сгенерируйте и просмотрите документацию снова:

faststream docs gen app:app
faststream docs serve app:app

AsyncAPI AsyncAPI2 AsyncAPI3

В http://localhost:8000 вы увидите:

  • На первом скриншоте:
    • Заголовок “User Message Processor” и описание приложения в верхней части страницы.
  • На втором скриншоте:
    • Очереди input-queue, output-queue и публикация output-queue с описаниями из докстрингов.
    • Сообщения из input-queue публикуются в output-queue после обработки, благодаря @broker.publisher. 🎉
  • На третьем скриншоте:
    • Поля UserMessage с описаниями и примерами из Field.

Шаг 4: Практическое задание 📚#

Закрепите знания с помощью заданий:

  1. Добавьте в модель UserMessage поле timestamp: datetime с Field, включая description (например, “Время отправки сообщения”) и examples (например, "2023-10-01T12:00:00"). Сгенерируйте документацию и проверьте, как оно отображается.
  2. Измените докстринг для check_result, добавив больше деталей (например, “Логирует результат обработки сообщения из output-queue для дальнейшего анализа”). Убедитесь, что это отражено в документации.
  3. Добавьте второй @broker.publisher("final-queue") к handle_message и проверьте, как AsyncAPI-документация показывает публикацию в обе очереди (output-queue и final-queue).
  4. (Дополнительно) Добавьте параметр version="1.0.0" в FastStream и проверьте, как он отображается в веб-интерфейсе.

Что дальше? 🗺️#

Вы научились генерировать и просматривать AsyncAPI-документацию для вашего FastStream-приложения, включая данные о публикации сообщений! 🎉 Это отличный способ делиться спецификацией с командой или документировать проект. В следующем разделе мы подведем итоги и расскажем, как продолжить изучение FastStream. Перейдите к Что дальше?, чтобы узнать о других брокерах, интеграциях и ресурсах.

Если у вас есть идеи, вопросы или нужна помощь, загляните в официальную документацию FastStream, пишите в Telegram или Discord. Продолжайте документировать и кодить! 🚀