Что не так с OpenAPI?

У вас на проекте порядок с документацией на API? Скорее всего нет. И в нашей компании порядка не было.

Не будем рассказывать, к каким печальным последствиям приводит ошибочная, устаревшая или вовсе отсутствующая API-документация. Почему же на большинстве проектов не удаётся решить такой, казалось бы, несложный вопрос?

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

Например, OpenAPI — самый распространённый язык описания REST API. Писать на этом языке настолько больно, что разработчик никогда не упустит шанс этого не делать (вот хороший пример отношения к OpenAPI).

Возьмём простейший API с одним ендпоинтом:

Пусть этот ендпоинт возвращает в ответ с кодом 200 такого вида:

В этом случае программист вынужден написать на языке OpenAPI 23 строки (!):

Реальные API частенько занимают не 23 строки, а несколько тысяч строк (вот, для примера, API Твиттера на 13 тысяч строк).

Существуют даже специальные инструменты — визуальные редакторы OpenAPI, которые позволяют писать OpenAPI-код не руками, а с помощью графического пользовательского интерфейса (например, https://stoplight.io/). Правда, эти инструменты не слишком помогают: вместо того, чтобы набирать много строк OpenAPI-кода, теперь нужно много кликать мышкой.

В результате, в реальных проектах происходит следующее:

Последний вариант, на первый взгляд, кажется замечательным решением. Для многих фреймворков существуют генераторы, которые автоматически создают OpenAPI-спецификацию на основе программного кода сервиса. И это, действительно, прекрасный способ, но, к сожалению, далеко не во всех проектах его удаётся применить, и вот почему:

Интересно, что все перечисленные недостатки генераторов проявляются в большей степени в крупных проектах. Именно поэтому в больших системах практически всегда используют подход “Spec First”.

Подведём итог (цифры даны примерные):

Это удивительно, насколько серьёзные последствия происходят из такой, казалось бы, незначительной вещи, как «неудобный язык описания API»! Из-за этой «мелочи» разработчики упорно саботируют документирование API, в результате чего огромное число существующих API описано плохо, либо не описано вовсе.

Во всём сказанном мы убедились на собственном опыте. За несколько лет мы перепробовали все возможные варианты документирования API: на некоторых проектах мы писали OpenAPI-документы вручную, на некоторых создавали их генераторами, на некоторых отпускали весь процесс на самотёк.

Однажды мы решили, что больше так жить не хотим.

Мы были уверены, что существует какой-то другой, более простой способ описывать API. Однако то, к чему мы в итоге пришли, удивило даже нас.

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

Показать пример — это самый простой и натуральный способ передачи знаний. Видимо, так устроен наш мозг. Можно долго, подробно и запутанно что-то объяснять, а потом показать пример — и всё сразу встаёт на свои места.

Можно ли использовать пример данных для формального описания схемы данных? Конечно! Нужно только договориться о формальных правилах интерпретации примера данных. В большинстве случаев эти правила считываются вполне интуитивно. Возьмём всё тот же пример данных:

Этот пример интуитивно считывается нами в виде следующих четырёх требований к структуре данных:

Возникает вопрос: а если захочется добавить к этим требованиям ещё какое-нибудь «хитрое» требование, которое нельзя выразить с помощью примера данных? Например, если мы захотим сказать, что свойство "name" в этом объекте не обязательное? Опять идём к программистам и подсматриваем, как они это делают. В этом случае к примеру данных они добавляют всем привычные комментарии в свободной форме:

Этот неформальный способ тоже можно легко формализовать. Мы решили, что будем помещать после знака комментария маленький json-объект с описанием всех дополнительных требований к соответствующему свойству. Получилось так:

Шикарно!

Если бы мы знали, какой огромный путь нам придётся пройти от первой идеи языка до рабочей версии, которую можно использовать в реальных проектах, мы бы пришли в ужас и поняли, что это безумие. Но, к счастью, мы не знали об этом и принялись за работу. Вот важные принципы, которые мы для себя обозначили:

Через пару лет работы мы получили довольно симпатичный язык. Вот, например, описание приведённого выше API (в самом начале статьи):

Первая строка "JSIGHT 0.3" — это название и версия языка. В остальном всё должно быть понятно без комментариев. Напомним, на OpenAPI то же самое описание заняло 23 строки.

В дополнение к языку мы разработали минимальный набор инструментов:

Мы попробовали всё это в трёх наших проектах, и вот что уже можно сказать:

Оказалось также, что язык можно использовать для черновых набросков прямо во время обсуждения структуры будущего API. Происходит это так:

Теперь проектирование API происходит у нас ровно за одно совместное совещание. С OpenAPI такое нельзя даже представить — на нём невозможно создавать быстрые эскизы. Раньше совещания происходили в 2–3 и более итерации, в промежутках между которыми аналитик фиксировал идеи на OpenAPI — так, как он их понял во время предыдущего совещания. После этого он рассылал OpenAPI-файл всем участникам, и (ну конечно же!) оказывалось, что участники друг друга неверно поняли, и нужно собираться снова. Получилось, что новый язык изменил наш привычный бизнес-процесс дизайна API.

И всё-таки, мы признаём, что несколько сошли с ума. Придумывать новый язык в наше время — это, прямо, что-то экстраординарное. По крайней мере для REST API весь мир уже использует язык OpenAPI. Захотят ли люди переходить на что-то новое, если уже привыкли работать на старом?

Непростой вопрос. Вся история IT-индустрии говорит о том, что сложные и машинно-ориентированные технологии обязательно уступают место простым и интуитивно-понятным. Если разработчику больно работать с чем-то, то рано или позно появится замена. Так когда-то произошёл переход от XML к JSON. Так когда-то SOAP уступил место REST. Так, скорее всего, случится и с OpenAPI. Но когда это случиться? Каким образом это произойдёт? Что придёт на смену?

Может ли наша безумная попытка претендовать на преемника OpenAPI?

Мы искренне верим в это! Но, как говорится, будущее покажет.

Мы надеемся, что эта статья была интересна. Мы затронули сложные, неодназначные вопросы, на которые пока еще не существует общепринятных ответов. Будем рады вашим комментариям и мыслям. Если любытно, можете посмотреть наш код на гитхабе, мы всё выложили в опенсорс.