Python & OpenAPI
Покопался в OpenAPI и его интеграции с Python. Глубоко не лез — только чтобы закрыть собственные вопросы.
OpenAPI — спецификация API web-сервисов, выросшая из Swagger — описывает свойства API, чтобы по описанию генерировать документацию, клиентские и серверные библиотеки.
Swagger — проприетарная штука, OpenAPI — открытая. Поэтому сам Swagger я не смотрел — в наше время не стоит завязываться на такое, если у вас нет мешка с деньгами и вагона с юристами.
Также не смотрел интеграцию OpenAPI с другими языками. Где-то всё будет лучше, где-то — хуже. Думаю, лучше всего поддерживаться OpenAPI должно для JavaScript, так как фронтендерам оно больше всех пользы несёт.
Далее, тезисно, моё мнение.
Общая концепция разумна и актуальна. Реализации с большего рабочие. Но практики использования спецификации ещё не устаканились.
Лучше всего польза спецификации заметна в документации, генераторов которой уже много. Кроме визуальных рюшечек, самые продвинутые из генераторов позволяют прямо из документации делать запросы к серверам — очень удобно. Подобный стенд будет полезен даже если у вас нет ни слова самой документации.
Если есть возможность дёшево получить OpenAPI спецификацию — делайте, документация окупит затраты.
Генерировать серверный код по спецификации API считаю неразумным в большинстве случаев. Это только для лютого энтерпрайза подойдёт, чем вы, скорее всего, не занимаетесь.
А вот генерировать спецификацию по коду сервера сам боженька велел. При грамотной реализации — это не только бесплатная документация, но и дополнительное давление в сторону наведения порядка в коде.
Сейчас в сообществе Python предпринимается несколько попыток сделать фреймворк с генерацией OpenAPI спецификации. На мой взгляд, самый перспективный — FastAPI.
FastAPI обладает понятным API, достаточной документацией себя, из коробки умеет раздавать вашу документацию. Предположу, что он может стать лидером среди питоновских web-фреймворков. Тарантогу я решил делать именно на нём.
Теоретически, спецификация должна быть удобной для генерации клиентского кода. Но в случае Python всё не радужно. Скорее всего в других языках тоже есть проблемы.
На мой взгляд, генерировать клиентские библиотеки по спецификации будет удобно, если у вас очень простое API и / или его очень много. В этом случае для вас либо сразу будут работать существующие генераторы, либо вы сможете выделить человека, который будет их докручивать для ваших нужд. А докручивать придётся.
Проблемы тут две, как две стороны одной медали.
Кастомные генераторы, специфичные для языка, каждый автор пилит под себя и свои нужды. Это касается, в частности, генерации структур данных.
В основном и универсальном инструменте для генерации кода по OpenAPI — openapi generator, наоборот, всё обобщенно. В результате для каждого конкретного языка функциональность развивается медленно и не успевает за трендами.
Поэтому большинство генераторов клиентского кода, ориентированных только на Python, заброшены (судя по истории коммитов) или решают частные задачи. А генератор в openapi generator завис в чистилище рефакторинга — их сейчас два: устаревший и актуально-экспериментальный. Экспериментальный не умеет в asyncio, а старый умеет, но больно криво — через потоки.
Как я уже упомянул, с генерацией структур данных проблемы. Тип AnyOf, например, в openapi generator не умеют генераторы ни python, ни java.
По этим же причинам я не думаю, что разумно использовать генерацию клиентских библиотек во время прототипирования — устанете согласовывать изменения с возможностями генератора.
Поэтому клиентскую библиотеку, по крайней мере для Python, я решил собирать руками.