Зачем OpenAPI?
Чего не могу понять, так это одержимость OpenAPI. Казалось бы, нужна апишка на сайте — ну, сделай как тебе удобно. Но люди берут OpenAPI, крафтят спеку, генерят по ней контроллеры, схемы, тесты. Превозмогают, потеют и потом рассказывают: смотрите, наша апишка по стандарту OpenAPI.
А кого волнует этот ваш OpenAPI? Расстрою: никому не интересно, какая у вас
апишка. Пользователю все равно, что гоняетя под капотом. Для программистов на
Питоне, как правило, пишут клиентские библиотеки. Вызывая метод
client.get_user(id=42)
, программист в гробу видал, что там у вас — GET
,
POST
, джейсон или XML. Никто на это не смотрит.
Если точнее, на это смотрят только кложуристы, потому что для них клиентских библиотек никто не пишет. Но кого интересуют проблемы кложуристов? Они сами напишут клиент поверх чего нужно.
За много лет я не припомню, чтобы от OpenAPI была какая-то польза. А вот проблем — целый мешок. Это стандарт, которому нужно следовать; это определенные инструменты, которые навязывают игру. Инструмент X написан на Руби, ставь его и миллион пакетов. Инструмент Y написан на Ноде, ставь ее тоже и качай половину npm. Я неделю настраивал swagger в докере, чтобы он показывал веб-страничку со спекой. Команда привязала гирю к ноге и удивляется: почему разработка идет так медленно?
Когда мне нужна апишка, я делаю простой RPC: команда-параметры, команда-параметры. Все в теле запроса, а не как в REST, где один параметр в заголовке, второй в адресной строке, третий черт знает где. В теле гоняю либо JSON, либо message pack в зависимости от content type.
Это просто, это быстро, это прозрачно. В коде большая мапа вида
{action {doc ...
schema-in
schema-out
handler ...}}
По текущей команде я вынимаю схему, проверяю вход, вызываю функцию handler
с
параметрами. Если дебаг, то проверяю выходные данные. Один раз настроил этот
словарь и потом только наращиваешь.
Если нужна документация, пишется код, который пробегает по словарю и рендерит
markdown-файл. В нем список команд, описание из поля doc
и схемы
ввода-вывода. Если нужно, md-файлик рендерится в HTML или PDF.
Но серьезным людям этого не понять. Им нужна OpenAPI-спека, чтобы что-то генерить и чему-то соответсвовать. Пишутся запредельные объемы тулинга под OpenAPI. Бывает, в Кложу приходит бывший рубист и заводит песню: мол, в моих Рельсах есть библиотека, которая по спеке сгенерит контроллер и модели, напишет тесты, а у вас в Кложе ничего нет… блин, потому я и довольный, что нет.
На самом деле я был разок в проекте на Кложе, где по OpenAPI-спеке генерили код. Два слова: это ужасно. Ни при каких обстоятельствах не сяду за это снова. Генерация — это стремно, это хрупко, это километровые диффы. Духота, трение и тошнота.
И никому не прихоит в голову спросить — зачем? Какую проблему ты решаешь своим OpenAPI? Зачем соответствовать чужому стандарту, который не контролируешь? Чтобы что?
Нашли ошибку? Выделите мышкой и нажмите Ctrl/⌘+Enter
Роман, 19th Dec 2024, link
Унификация.
Сэкономить на разработчиках. Ну вроде же это очевидно. Ну и это же открытый стандарт. Чем больше людей ему следуют, тем проще найти специалиста, а не ковыряться в вашем кастомном тулинге.
Оппаньки - давно ли следование стандартам стало иметь негативные коннотации?
Вот это «пишется код» и есть проблема. Теперь в нашей компании есть код для генерации документации который надо поддерживать. А если вы завтра увольняетесь, кто будет его поддерживать? Или будем писать заново? Или каждый прогер, чтобы почитать документацию должен себе написать программу, которая эту документацию сгенерит?
Давайте я разовью идею. Надо сразу и операционку под себя писать. Ибо «Зачем соответствовать чужому стандарту, который не контролируешь? Чтобы что?» - там же большая часть драйверов вообще на вашем железе не используется, каждый релиз куча багов фиксится . Гораздо лучше сразу написать свою и сразу правильно по простому - без лишнего мусора.
Юстас, 19th Dec 2024, link
Поздравляю, Вы нащупали одну из причин любви серьёзных людей к Линуксу. Не нравится - отрежь, не хватает - допиши. И всё не рассыплется ко всем чертям при завтрашнем апдейте. А если и рассыплется из-за дебила, протолкнувшего в LTS изменение одной нехорошей константы, - всё задокументировано и если и не решается водиночку, то вместе точно поправимо.
Роман, 20th Dec 2024, link
«В огороде бузина, а в Киеве дядька» - при чем тут Линукс? Речь о следовании единому стандарту, вместо выдумывания своих уникальных решений на каждый чих. И о том, что тезис «не надо пользоваться стандартом, который не контролируешь» как минимум странный если не сказать больше.
Вообще хотелось бы узнать сколько стандартов контролирует автор и как ему живется без контроля над например стандартом напряжением в сети, над стандартами передачи данных - USB и HDMI видимо пользоваться зашкварно.
Да лаадно. Как раз таки рассыплется. Я к слову таких «дописывателей» повидал.
В линуксе? Все задокументировано? Ха-ха-ха.
Это вы про баги и уязвимости , которые не фиксят десятилетиями?
Юстас, 20th Dec 2024, link
Вы выбрали подозрительно немноголюдное место, чтобы юродствовать. Обычно блаженные выбирают места с большей проходимостью и лучшей узнаваемостью конкретного блаженного. Хабр, например.
Вы хотели ОС, которую можно пересобрать под ключ, - нате, Линукс.
Наш единый стандарт в лице лично Торвальдса живёт и здравствует.
Для любителей странного типа Вас специально есть опция взять максимально высокий и низкий уровни взаимодействия (устройства ввода-вывода и кернел соответственно) и мастурбировать себе прослойку между ними с нуля.
Если и это мимо - может, угомонитесь и попробуйте объяснить более читабельно, как Вы видите написание стандартизированной ОС с нуля?
Более абстрактное трогать не буду, пока есть сомнения во вменяемости собеседника.