Skip to content

Расширенное использование

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

Обзор архитектуры

Архитектура FastOpenAPI вдохновлена FastAPI, но не привязана к конкретному фреймворку. Основные компоненты включают:

  • BaseRouter: Базовый класс, содержащий логику регистрации маршрутов, генерации схемы OpenAPI и обработки запросов/ответов. Не зависит от конкретного фреймворка.
  • Роутеры под конкретные фреймворки: Подклассы BaseRouter, такие как FlaskRouter, StarletteRouter и др. Реализуют специфические особенности каждого фреймворка (например, как регистрировать маршруты или подключать документацию).
  • Модели Pydantic: FastOpenAPI использует Pydantic для моделирования данных. Модели применяются как для тела запроса, так и для ответа, а также для генерации схем JSON Schema в OpenAPI.
  • Генерация схемы OpenAPI: FastOpenAPI использует метаинформацию о маршрутах (пути, методы, параметры, модели и т.д.) для построения схемы OpenAPI (версии 3.1.0, так как Pydantic v2 формирует совместимые схемы). Схема доступна в формате JSON по эндпоинту /openapi.json.
  • Интерфейсы документации: FastOpenAPI включает статические страницы или ссылки на Swagger UI и ReDoc. При переходе на /docs или /redoc вы получаете HTML-страницу с подключённым интерфейсом и ссылкой на /openapi.json.

Поток обработки запроса

  1. Запрос поступает во фреймворк (например, Flask) к маршруту, зарегистрированному через FastOpenAPI.
  2. Обработчик был зарегистрирован с помощью декоратора @router.get/post/....
  3. До вызова функции FastOpenAPI (через BaseRouter) выполняет парсинг и валидацию:
  4. Параметры пути извлекаются из URL (обычно делает сам фреймворк).
  5. Параметры query, заголовки и тело парсятся. Параметры валидируются по сигнатуре функции или моделям Pydantic.
  6. Функция вызывается с валидированными данными. Если валидация не прошла — возвращается ошибка и функция не вызывается.
  7. Возврат из функции:
  8. Если возвращены данные — FastOpenAPI сериализует результат. При наличии response_model он валидирует и сериализует результат. Без модели — просто сериализует результат как есть.
  9. Если выброшено исключение (например, ResourceNotFoundError) — FastOpenAPI отлавливает и формирует ошибку.
  10. Фреймворк отправляет итоговый JSON-ответ клиенту (для успеха и ошибок).

Расширение под новые фреймворки

Одна из целей FastOpenAPI — расширяемость. Если ваш фреймворк не поддерживается, вы можете реализовать собственный роутер.

Чтобы создать интеграцию:

  • Наследуйтесь от fastopenapi.routers.BaseRouter.
  • Реализуйте необходимые абстрактные методы. Например, BaseRouter ожидает:
  • Метод для добавления маршрута во фреймворк.
  • Возможно, метод запуска приложения (не всегда требуется).

  • Добавление маршрутов /docs, /redoc, /openapi.json (часто делается в __init__ или вспомогательном методе).

  • Изучите реализацию существующих роутеров. Например:

  • FlaskRouter.add_route вызывает Flask.app.add_url_rule.

  • StarletteRouter.add_route добавляет в Starlette.routes.

  • BaseRouter предоставляет утилиты вроде get_openapi_schema() для генерации схемы — их можно использовать и в новых адаптациях.

Например, если бы вы захотели интеграцию с Fastify (гипотетически, так как это Node.js), вы бы написали FastifyRouter(BaseRouter) и реализовали регистрацию маршрутов под Fastify.

Также вы можете кастомизировать существующий роутер:

  • Наследуйтесь от существующего роутера и переопределите методы. Например, сделать FlaskRouter с префиксом или с другим путём документации.
  • Переопределить поведение генерации схем или ошибок — это требует понимания структуры BaseRouter.