Альтернатива OpenAPI и Swagger

А какая у тебя цель? Тебе конкретно спеку нужно получить или Swagger UI? Елси второе, то ищи расширение для своего фреймворка, которое сделает всё за тебя, если первое, то альтернатив уровня индустриального стандарта, которым openapi и является, нет даже близко.

Цель: сделать спеку.

В моем случае не получится подключить расширение для моего фреймворка: придется много чего переписать или ровно также вкорячивать аннотации (python, flask без restplus). Писать в каком-нибудь mkdocs банально долго и больше вероятности сделать опечатку.

альтернатив уровня индустриального стандарта, которым openapi и является, нет даже близко.

Печальбеда(

А проект уже готов или только начинается? Если только начинается, и в дальнейшем намечается хоть какая-то нагрузка, то лучше взять FastAPI. Там и сваггер нахаляву, и приведение типов, которое на фласке нужно тащить с расширением, либо костылять, ну и асинхрон.

Уже готов, но там в пределах ~30 раутов. Тоже смотрел FastAPI и даже думаю над вариантом сделать переход на него.

GraphQL.

да, и хотелось бы обойтись без лишних велосипедов

GraphQL.

Спасибо, интересно. Можно чуть более развернуто?

Не-не, только REST :)

Вроде GraphQL - просто расширение идеи REST.

По сути тот же REST с возможностью попросить подмножество данных прямо с фронтенд. Спросить меньше - фундаментально безопасная операция по сравнению с полной выборкой. Можешь переизобрести GraphQL через GET /users?fetch_only=name,age. Ну плюс еще реляционные фичи на любителя

Можешь переизобрести GraphQL через GET /users?fetch_only=name,age

Уже изобрели JSON:API. Только оно не совсем живое, да и по фичам, удобству и библиотекам/сообществу сильно проигрывает GraphQL.

Вообще обычно делается наоборот - сначала спеку пишут, а потом генерируют по ней клиент или сервер-заглушку. Хотя встречается и подход с генерацией спеки из аннотаций. А так чтобы спека генерилась из рандомного куска питонятины не встречал

Уже изобрели JSON:API. Только оно не совсем живое, да и по фичам, удобству и библиотекам/сообществу сильно проигрывает GraphQL.

выглядит юзабельным

Удачи!

В старые времена спеку SOAP-сервиса можно было мышкой натыкать. А реализацию можно было в визуальном редакторе бизнес-процессов запилить. Из кода надо было писать разве что только сниппеты нетривиальной логики. А протестировать через SoapUI. Вот уж где дзен-то был, не то что этот ваш REST.

Да и всё было солидно-ентерпрайзно, с валидацией, сертификатами и человекочитаемыми логами.

Ты шо, там же был xml! Да и ваще был продуктом микрософта! Да затакое тебя изгнать и забанить надо!

На самом деле соап в ентерпрайзе зачастую к такой лапше приводили с тонной различных расширений, именно из-за простого и быстрого пути - нанять индусов, чтоб они чего-то там мышой наготовили, что лично мне как-то его не жалко, но да, при примых рукам была конфетка.

Альтернатива не писать описание +) Есть application/hal+json , который ИМНО может быть заменой детальному описанию. Во всяком случае я поработал с ентерпрайзнутым продуктом на этом самом hal - нужно было в хвост и в гриву использовать рест, пространной документации в которой много было не описанно, было более чем достаточно.

Ты шо, там же был xml!

Как-будто что-то плохое. Я до сих пор не понимаю как можно было променять такой мощный и универсальный язык на убогий json в котором даже схемы-то в стандарте нет. Я уж и не говорю про yaml.

именно из-за простого и быстрого пути - нанять индусов

Сейчас такая же фигня, только вместо SOAP, J2EE и WebSphere/Weblogic, теперь Spring Boot, Swagger, REST API и микросервисы.

на убогий json в котором даже схемы-то в стандарте нет. Я уж и не говорю про yaml.

Ты шо! Принцип прост - чем хуже тем лучше! Я вот с ужасом жду, что там будет популярно апосля ямля.

Сделай свою велоспеку, и перегонку её в openapi.

Я сейчас костылю на jinja

Ну камон) понятно, что нет лучше доки, чем та которую не пришлось писать, но, увы, не все такие прожженые. Но за наводку спасибо)

Что-то круто ты взял. Тебе надо из одной структуры данных сделать другую структуру данных. Тут вопрос только в удобоваримости твоей структуры для тебя. Там может вообще быть какая-нибудь херня, которая подразумевает какие-нибудь профили, группы и прочую хрень.

Так у меня задача не про то, чтобы сделать аналог свагера, а избегать опечаток (поля модели, например) и на выходе получать документацию с примерами. Эта реализация проживет какое-то время, а потом выкину и перейдем уже на тот же свагер, который автогенериться как у нормальных людей.

Жил-был стартап. Сначала пилили как пилиться, а потом он рррраз и полетел вперед. Команда фронтенда удволилась и список фич для бекенда раздулся. И нужно фичи писать, и доку тоже. А времени переезжать прямо сейчас на нормальный автоген ну никак нет.

Отчасти я исправляю собственную архитектурную глупость.

Так у меня задача не про то, чтобы сделать аналог свагера

Ну так всё правильно, его и не надо делать. Надо костыль сбоку, который будет делать свагер за тебя.

Имеется ввиду детальную доку. Просто хал сразу описывает все доступные переходы в самом запросе и подобрав удобочитаемые урл-названия, можно сократить кучу описываемой инфы и сосредоточиться на главном и тогда никакие генерялки описания и не нужны + при изменениях, описания ненужно перегенерять. В общем ИМНО одни плюсы.

А можешь какой-нибудь пример скинуть или хотя бы направление дать как гуглить?

Называется это штука Hypermedia. Начать можно отсюда https://habr.com/ru/company/aligntechnology/blog/281206/ примеры там тоже есть, правда насколько они сейчас актуальны я хз. а так https://yandex.ru/search/?clid=2186623&text=application%2Fhal%2Bjson&lr=2&redircnt=1626010420.1 +)

апд. в джаве есть вот такое spring-rest-hal для построения браузера хал ссылок - https://www.baeldung.com/spring-rest-hal , это в рамках темы топика, возможно, в твоём языке тоже есть нечто похожее.

Спасибо!

подозреваю, что ты пишешь на каком-нибудь гоусеке, если тебе эти говнонотации писать вручную нужно, потому как многие нодовские/питоновские либы сами генерируют эти схемы

я чет думал spring сам эту документацию генерирует, но я бы все равно вручную писать не стал, скриптами с регулярками взял бы все сгенерировал