Разработчики ленятся писать документацию или что делать?

Поддерживать актуальное состояние

выкатывать обновления на сайт документации?

Выкатка в процессе CI

так пусть автоматизируют один раз )

RAML  сыроват всё же;. Сам по себе он неплох, и в его основе лежат неплохие идеи. Но все вспомогательные инструменты (для той же генерации документации) находятся в сыром состоянии

@ayemelianov я это вижу как две категории инструментов — до написания кода (RAML / API Blueprint) и после написания кода (Swagger). Swagger хорошо сработал в вашем случае, не было подводных камней?

Кратко о моём контексте — аутсорс / аутстафф компания, проектов много, разработчиков много, есть ротации разработчиков, цена интеграции в проект высокая. Оцениваю как с помощью правильной и действительно нужной документации снизить стоимость.

Нормально сработал swagger.

Мы тоже юзаем swagger, пока не было проблем, я просто поправляю иногда синтаксис за разработчиками, например если когда я пошла проверять по запросам, что-то не работает явно какой-то из эндпойнтов например, а то что без души, да был такой эпизод, клиент хотел прям текстовую доку в стиле HTTP запрос на такой-то эндпойнт, тип запроса,  что принимает, каки епараметры обязательные, какие опциональные, что вернет код ответа, какие параметры авторизации, токены да нет, и краткий и живой юз кейс с настоящими параметрами, сделали, но всего 1 такой был, кому сваггер показался слишком стильным и модным)

мне нравится что из него можно напрямую без curl условного дернуть запрос

@Lananovikova а вот для чего дергать, если схема запроса / ответа описаны? Чтобы убедиться, что метод работает?

потестить

Это уже QA дело, а не писателя

Так то оно так, но в небольших командах часто один человек на себя берет несколько ролей.

Это да. Но нужно стремиться к совершенству

например код ответа не всегда описан верно, нужно посмотреть консистентна ли документация тому, что реально вернется

@Lananovikova мы эту задачу решили тестами, которые перед каждым деплоем (в том числе и документации) проходят

Андрей, Егор: подергать запросы полезно для того, чтобы понять, как всё работает.

Описания должно быть достаточно?