Одна из самых бесполезных вещей в айти — это Swagger. Так называется система, которая отображает REST-апихи в JSON-файле. Идея хорошая, но на практике вымораживает мозг. Давно порывался написать о ее минусах, и вот на днях опять подгорело.

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

Swagger это порождение мира node.js, столь мне отвратного. Это папка node_modules с миллионом микро-файлов, хрупкие сборки и прочие фу. К счастью, появились докер-образы, но и они не без греха. Так, образ swagger-ui нельзя запустить в read-only файловой системе. Если у вас Кубернетис, придется выкручиваться.

Усилия, направленные в русло Swagger, напоминают строительство пирамид. Масштабно, неэффективно и никому не нужно. Верный признак ущербности в том, что со всех сторон плодят еще более не нужные утилиты: убогий онлайн-редактор, CLI и, конечно, ОБЛАЧНУЮ учетную запись. Для утилиты, которая по JSON рисует HTML.

Те, кто топят за Swagger, не понимают, как устроена документация в фирмах. Дело в том, что JSON не может нормально передать текст, он для этого не предназначен. Использовать для документации язык, в котором нет мульти-строк, средств акцента, ссылок и прочего — это прохладная идея.

Нормальная документация — это семейство markdown- или asciidoc-файлов, объединенных в проект. Человек садится за редактор и пишет текст ручками. Расставляет акценты, ссылки, сноски. Это трудная работа, но только так получается достойная документация.

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

Верный признак того, что Swagger это ущербная технология — им не пользуются самостоятельные компании. За всю карьеру я ни разу не видел, чтобы условный Гугл, Яндекс, Амазон и прочие показывали документацию через Swagger. В фирмах разный подход, но как правило это HTML с написанным человеком текстом. Вот несколько примеров:

Кто там еще? Вконтакт, Dropbox, банки (Тинек, Сбер)… ни одна значимая фирма не пользуется Сваггером. По моим меркам это был бы позор уровня студента.

Стандартный шаблон Сваггера ужасен. Взгляните на официальное демо:

Тут красненький, тут желтенький, зеленый, выпадашечки, блин, цирк. Школьное поделие, а не документация. Этот шаблон не вписывается ни в один дизайн, каждый элемент чужероден. Нужно несколько дней на то, чтобы сверстать свой шаблон. Предлагать клиентам Сваггер — значит заведомо не уважать их.

Кроме убогого шаблона, Swagger предлагает утилиту для генерации кода приложения. Давайте честно: кто захочет строить проект на базе кодогенерации, написанной неизвестно кем? Этот код однозначно уйдет в урну. Конечно, генерация пригодится студентам для курсовой работы по предмету “введение в веб-разработку”, но и только.

В общем, прекратите страдать фигней. Хотите нормальную документацию — поднимайте проект на Asciidoc, Wiki, GitBook, что угодно. Это трудно и требует навыков выражать свои мысли понятно. Может, пока апиха в разработке и меняется каждые два дня, нет смысла писать документацию. Но не вываливайте на клиентов интерфейс Сваггера. В нем отчетливо слышна машинная природа, и по всем признакам ясно, что эта страница не для людей.

← Dictionary-like Specs in Clojure

Ищу помощника →