Если у вашего бэка все методы даже не заполняют окно редактора, и вы сами пишете фронт, то можно и не документировать, если этого не требует заказчик.
Если разработчики бэк и фронт частей разные, то над документированием уже стоит не только задумываться, но и начать реализовывать.
О размещение документации в этой статье говорить не будем, но в подборке материалы конечно же будут.
Зачем? Вот я, например, запушил по заявке новый функционал, который нужно передать фронтэнд разработчику. Я начинаю писать ему в корпоративном Битриксе24 (далее просто Битриксе), что-то вроде
Татьяна, POST /api/product/{id}/store ...
А продукт имеет кучу свойств, для которые нужно указать тип и хоть как-то описать. В процессе описания могут возникнуть ошибки или процесс описания разбивается на несколько сообщений и после каждого может возникать диалог. Да и сам процесс описания становится невыносим, когда редактор сообщений не имеет снипетов и вообще не знает команд IDE.
В общем это, в лучшем случае, утомляет, в худшем - выносит нервную систему.
Можно конечно писать в условном gitlab-е. Там редактор комментариев в ишью уже на уровне, но все же это описание через какое-то время уже не будет соответствовать актуальному состоянию функционала.
В ситуации когда команда разработчиков большая, то документация уже просто необходимый атрибут проекта.
Развитый функционал или методы с большой нагрузкой, к виде большого количества свойств удобнее обозревать в документации, чем в файлах с роутами и их контроллерами.
Ну и конечно, когда Документация к API это часть вашего проекта, которая предоставляется сторонним разработчикам, например, для интеграции. Она должна быть описана максимально подробно, чтобы они, сторонние разработчики, как можно меньше задавали вопросов.
Я, в силу того, что написал множество интеграций, имею представление о хорошо и плохо оформленных документациях.
Удобно работать с REST API оформленном на каком-нибудь движке, где навигация и показ атрибутов интуитивны. С SOAP несколько сложнее, однако даже в PDF документе, можно хорошо описать API.
Почему же есть много того с чем не хочется работать? Во многом это вопросы к разработчикам. Нехватка времени. Уникальность продукта, когда нет альтернатив. Другие факторы, которые позволяют не выделять ресурсы под написание качественной документации к API.
Недавно я сам столкнулся с ситуацией, когда один из клиентов долго не мог осилить метод для бронирования авиабилета. Предыдущие интеграторы уповали на отсутствие типовых сценариев и редко задавали вопросы, да и проблемы в основном были связаны с работой тестового сервера. Возможно имеет место быть неопытность разработчика, так как ошибки были допущены при заполнении полей типа "country_id", в которых передавали значения типа "RU" вместо идентификатора страны.
Но в документации для таких процессов как поиск и бронирование авиабилетов должны быть примеры заполнения нагрузочных параметров, что отсутствовало в документации моего проекта. Однако так совпало, что в другом проекте потребовалось создавать документацию для интеграторов. За основу взяли спецификацию openApi, которая подходит для обоих проектов. Дабы не разжевывать при каждой следующей интеграции очередному разработчику, что нужно передавать в том или другом свойстве выделили ресурсы для написания документации, в которой будут развернуто описаны сценарии работы с заказами от поиска мест до обилечивания бронирования, а так же описание нагрузки методов с примерами передаваемых значений.
Поэтому пишите документацию, даже когда кажется, что и так все понятно. Потому что сейчас понятно, а через месяц уже ничего не понятно, особенно, когда работаешь над несколькими проектами.