Комментарии 4
Самая адовая документация по API с которой приходилось работать - это RKD от рейтерс. Хорошее почему-то не запоминается
Хорошо бы добавить опрос - кто чем пользуется (Swagger UI, RapiDoc, Redoc, other).
Пробовали Redoc - откатились обратно на Swagger UI.
Причина тривиальна - пользователям проще.
В 2016 я получил свой первый оффер в качестве программиста, в одну финтех-компанию в клиентскую поддержку. Директор рассказала, что на разрабов сыпется вал вопросов по интеграции и что "ребятам надо бы код пилить, а у них полный швах с вопросами от клиентов, и вот мы решили взять специального человека для этого".
Вникнув в проблему, я обнаружил что документация API представляет собой docx-файл, в котором намешаны разрозненные данные об услугах организации, об ее конкурентных преимуществах (!), чуть ли не в строку перечислены точки входа в API, и иногда пропущены объяснения за какой функционал какая точка отвечает. Вплоть до разных шрифтов (которые конечно ни на что не влияют, но лопни мои глаза)...
Я был новеньким в компании, над программистами висел полугодовой бэклог и мои вопросы чаще всего оставались без ответа. Тогда я взял Postman, перелопатил весь API с начала до конца, попутно пофиксил пару багов и добавил недостающие как мне казалось методы к нему (спросив, конечно, у тимлида).
Действительно: если хочешь в чем-то досконально разобраться — напиши об этом туториал...
Этот подход сработал и через пару месяцев я выкатил новую доку (на сей раз в html, и оформленную как ожидают программмисты), запихал ее в подходящий пункт меню на сайте, а вордовский файл упразднил. Придумал включать в доку эндпоинты только для тех услуг, на которые был подписан текущий клиент, благодаря чему показываемая на экране дока сухднула раз в 5 — каждый конкретный клиент пользовался отнюдь не всеми услугами компании.
Результат не заставил себя долго ждать: изо всего вала вопросов новых клиентов остался... один. Его задавали практически 100% новых клиентов и звучал он "а как в 1С сделать POST запрос?", на который я загуглил ответ (сорри, я не 1Сник) и вывесил его на видное место в желтом диве :)
"Мавр сделал свое дело, мавр может уходить". Я был готов к тому что мненя уволят за ненадобностью, но мне неожиданно повысили зарплату и перевели в одтел разработки, сохранив обязанность отвечать на вопросы клиентов. Я выкатил тикет-систему (запилив прозрачную авторизацию в ней при переходе из клиентской части) и с ней стало легко систематизировать вопросы и отвечать уже заранее заготовленными (простите если кого этим оскорбил) ответами.
Вся эта конструкция из новой доки и тикет-трекера проработала примерно с год, пока второе лицо в организации (о, у него была прикольная должность "муж директора") не обнаружило, что когда-то написанный им docx-файл упразднен и заставил меня... убить мою доку и восстановить его файл.
Но это уже совсем другая история, в которой "второе лицо" прилюдно получило от директора, люто возненавидело меня и в конце концов мне из-за этого пришлось уйти...
Увы rapidoc из коробки а) не понимает yaml (не беда, я пока на json), б) не понимает json-ref (беда, вести апи в одном файле можно разве что для helloworld). в) опять же без допила из-за CORS не может работать локально. В то время как у Redoc cli, лихо встраивается в CI/CD. Внутрь я к ним не лез, но пока как-то так. Ждем вторую часть с интересом!
Как документировать публичные API для продукта. Большой гайд, часть 1