Комментарии 8
Что-то у меня голова закружилась. С ног на голову перевёрнуто. Как раз-таки ключевая особенность FastAPI это чудесный встроенный генератор OpenAPI из Pydantic-моделей. А писать Pydantic-модели проще некуда и уж намного приятнее всяких Swagger Editor-ов.
Вы правы, но многие выбирают Swagger для документации API. Если вы всё равно пишете Swagger, то почему бы не сократить часть работы? В случае с FastAPI это может быть не так очевидно, но тот же подход применим к Flask, где он действительно полезен.
Лично мне приятнее писать Swagger, чем Python. А так же я использую одну спецификацию для фронта и бэка, что сильно упрощает разработку.
Но ведь в FastAPI уже из коробки есть Swagger UI. Я не пишу его, он там работает автомагически. Зачем выбирать, когда он уже там есть?
Я вижу противоестественное использование инструмента и это меня напрягает. Если смотреть в масштабе команды, когда можно выбирать инструменты, то FastAPI полностью закрывает и валидацию и автодокументацию. Это его лучшие стороны. Мой опыт с JSON Schema и другими валидаторами (и другими стеками) позволяет сравнить и сделать вывод, что FastAPI здесь крайне хорош. Рекомендую почитать, как автор объясняет причину создания FastAPI: https://fastapi.tiangolo.com/alternatives/#swagger-openapi
Про Flask и сокращение работы - скажу кратко и поэтому довольно категорично. В новом проекте я бы забыл про Flask и попросил бы аналитиков работать с вики-текстом и схемами и не тратить время на собирание yaml руками. Само собой, у фронтэнда и тестировщиков будет всегда актуальный Swagger UI, бесплатно. Если в проекте Flask и автогенерация Pydantic моделей - это не мой проект, извините.
С ног на голову перевёрнуто
Не с ног на голову, а API first. Вот, например, статья объясняющая различия принципов code first и api first: https://habr.com/ru/companies/axenix/articles/694340/
И тот и другой принцип имеет свои плюсы и минусы и оба используются в разных проектах. Как мне кажется, code first даже более распространён в виду простоты реализации. Но ничего противоестественного в API first нет.
этот подход (API first) не что иное, как воплощение классических этапов разработки, о которых всё время твердят олды, но шарахаются Agile адепты: проектирование и системный анализ.
Мне очень понравился комментарий пользователя @lebedecиз статьи, что я привёл выше в этом комменте. Потому перепечатаю его здесь и посоветую прочитать статью, если тема вам кажется интересной.
ничего противоестественного в API first нет
API first это хорошо и понятно, и с этим нигде не спорил. Противоестественность вижу только в использовании конкретного инструмента, FastAPI. Ведь автор фреймворка подробно изложил свой подход, ссылка в предыдущем комменте. Взять инструмент и не пользоваться половиной его возможностей или пользоваться поперёк - не мой путь.
если тема вам кажется интересной
Да, тема настолько интересна, что каждый день по ней работаю. Во многих статьях красиво изложено на паре примитивных роутов и на типах integer и string. На практике бывают весьма развесистые джсоны на входе/выходе, с кучей разнообразных проверок, включая непустые массивы, диапазоны чисел, url и прочее. Можете подсказать видео, очень хочется посмотреть процесс, как с нуля собирается yaml для нетривиального API хотя бы на пять полноценных сущностей?
Если проект большой, много команд и есть отдельный опытный аналитик, то конечно же удобно и правильно сперва зафиксировать спеку. Я не лезу в такое, пишу только с позиции одной команды и проекта типа стартапа. Так вот, на мой взгляд FastAPI особенно хорош для стартапов, и удивительно и приятно видеть его заход в более крупные проекты.
Противоестественность вижу только в использовании конкретного инструмента, FastAPI
Что ж тут противоестественного. Возможность генерации спеки из кода никак не запрещает генерить из спеки код.
Ознакомьтесь со списоком генераторов. Тут есть минимум три генератора, которые создают pydantic модели из swagger-спеки:
https://openapi-generator.tech/docs/generators
Зачем-то ведь люди это делают.
И вот ещё по теме:
https://github.com/fastapi/fastapi/issues/519
Обратите внимание на реакцию сообщества на первый комментарий.
Реакция сообщества - это вы про 8 дизлайков в гитхабе? Это ни о чём. Я сугубо практик. Про connexion там верно подметили, вот инструмент гораздо более подходящий.
Ознакомьтесь со списоком генераторов
Даже пробовал похожее, для генерации нагрузочных тестов. Не впечатлило.
Вы не подумайте, мне нравится сама идея API first. Ещё бы поглядеть на видео как полагается спеку собирать, опенсорсными local-first инструментами, желательно не выходя из VS Code. Swagger Editor не предлагать;)
очень хочется посмотреть процесс, как с нуля собирается yaml для нетривиального API хотя бы на пять полноценных сущностей?
В этом процессе нет ничего особенно, по сравнению даже с тем, что описано в этой статье.
На практике (проектов среднего размера) скажу, что в API first подходе определённо есть ряд проблем:
несовершенство генераторов порой не позволяет описать спеку так, как хочется, потому что генератор чего-то не поддерживает. Иногда приходится править спеку, а иногда коммитить в генератор.
могут быть сложности с описанием правил валидации. В спеке не описать всех проверок, которые можно описать в коде. Но такие проверки надо и оставить в коде. Так что это не существенная проблема.
могут быть сложности с добавлением кастомных аннотаций (декораторов) к сгенерированным классам. Но мне такой необходимости удавалось избегать.
Но при Code first будет ряд других проблем связанных с построением процессов интеграции изменений в генерируемой спеке между несколькими компонентами. И на мой субъективный взгляд, проблем настройки CI в случае code-first - больше.
От документации к готовому API: Генерация кода из Swagger для FastAPI