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, я решил собирать руками.