FAQ (Часто задаваемые вопросы)

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

В: Что такое FastOpenAPI и чем он отличается от FastAPI?

О: FastOpenAPI — это не веб-фреймворк, а библиотека для добавления OpenAPI/Swagger-документации и валидации запросов/ответов в существующие веб-фреймворки (Flask, AIOHTTP и др.). FastAPI — это полноценный веб-фреймворк с нативной поддержкой OpenAPI. FastOpenAPI вдохновлён опытом разработки на FastAPI, но предназначен для предоставления аналогичных преимуществ в других фреймворках, где нет встроенной документации. Кратко: используйте FastAPI, если создаёте новый проект с нуля и хотите встроенное решение; используйте FastOpenAPI, если у вас уже есть приложение на другом фреймворке или нужно поддерживать несколько фреймворков с одной библиотекой.

В: Какие веб-фреймворки поддерживаются?

О: Поддерживаются:

AIOHTTP (асинхронный HTTP-сервер/фреймворк)
Falcon (поддерживает как ASGI, так и WSGI)
Flask (синхронный WSGI-фреймворк)
Quart (асинхронный фреймворк, похожий на Flask)
Sanic (асинхронный веб-фреймворк)
Starlette (лёгкий ASGI-фреймворк)
Tornado (веб-фреймворк и сетевая библиотека)

FastOpenAPI легко расширяем, так что в будущих версиях могут появиться и другие адаптеры. Вы также можете реализовать свой собственный Router (см. раздел "Advanced Usage") или предложить фреймворк авторам проекта.

В: Какие версии Python и Pydantic требуются?

О: FastOpenAPI требует Python 3.10+. Он использует Pydantic v2 для валидации и описания данных. Pydantic v2 генерирует схемы, совместимые с OpenAPI 3.1. FastOpenAPI уже содержит Pydantic v2 в зависимостях.

В: Как документировать авторизацию (JWT, ключи API и т.д.)?

О: FastOpenAPI сам по себе не реализует авторизацию, так как это зависит от фреймворка. Однако вы можете описывать схемы авторизации в OpenAPI-спеке. Например, можно вручную добавить securitySchemes в сгенерированную схему (см. Advanced Usage). Если вы используете токены в заголовках, можно просто добавить параметр token: str в сигнатуру функции и указать его в response_errors или описать в docstring. Проверку токена при этом выполняет ваше приложение (например, middleware или декораторы), а FastOpenAPI отвечает только за документацию.

В: Интерфейс документации (Swagger/ReDoc) не отображается или `/docs` возвращает 404. Что делать?

О: Убедитесь, что вы передали app при создании роутера (router = FrameworkRouter(app=app)). Без этого маршруты не будут зарегистрированы. Также проверьте, что приложение действительно запущено и слушает нужный порт. Если вы работаете за прокси или используете префиксы маршрутов, документация может быть доступна по пути вроде /<префикс>/docs.

В: Можно ли использовать FastOpenAPI вместе с другими генераторами схем (например, Flask-RESTx)?

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

В: Поддерживает ли FastOpenAPI dependency injection и другие фишки FastAPI (фоновые задачи, middleware и т.д.)?

О: Нет. FastOpenAPI не предоставляет систему внедрения зависимостей, как FastAPI. Он сосредоточен на маршрутах и документации. Для DI и фоновых задач следует использовать механизмы вашего фреймворка (например, Flask g, контекст приложения, или Depends в Starlette при ручной интеграции). FastOpenAPI просто вызывает вашу функцию, передавая извлечённые параметры.

В: Насколько стабилен FastOpenAPI для продакшн-использования?

О: Библиотека находится в активной разработке (pre-1.0). Многие ключевые функции уже реализованы, но возможны изменения. Лучше зафиксировать конкретную версию в requirements.txt. Сама генерация схем безопасна, так как работает только на чтение. Однако рекомендуется писать тесты, чтобы отслеживать потенциальные проблемы при обновлениях.

В: Как я могу помочь проекту или сообщить об ошибке?

О: Будем рады вашему вкладу в проект! Ознакомьтесь с разделом Contributing. Вы можете завести issue на GitHub (для багов, запросов фич и вопросов) или прислать PR. Очень приветствуется также улучшение документации, примеров и тестов.

В: Есть ли примеры реальных проектов, использующих FastOpenAPI?

О: В репозитории FastOpenAPI есть директория examples/ с примерами для всех поддерживаемых фреймворков. Это хорошая отправная точка. Поскольку проект относительно новый, примеры из реальных проектов пока немногочисленны. Если вы используете FastOpenAPI — расскажите об этом или поделитесь ссылкой на проект.

В: Какую версию OpenAPI генерирует FastOpenAPI?

О: FastOpenAPI генерирует схему OpenAPI 3.1.0 (так как Pydantic v2 использует JSON Schema, совместимый с OpenAPI 3.1). Это позволяет использовать новые возможности (например, oneOf, anyOf, nullable и др.). Swagger UI и ReDoc поддерживают 3.1, убедитесь, что у вас актуальные версии.

Если вы не нашли ответа — загляните в разделы Usage и Advanced, а также в README и issue трекер репозитория. FastOpenAPI развивается при поддержке сообщества, и ваш вопрос может помочь улучшить проект.