Чрезмерная честность граничит с глупостью (с) в оригинале «прямота»

Документируй это / Хабр
https://habr.com/ru/post/556400/

Кто пробовал SpringAutoRestDocs? На сколько облегчает документирование по сравнению со обычным Spring Rest Docs?

Я читал что вся команда должна использовать spring

Если куча микросервисов, то не обязательно. Даже стек в продукте разный.

Основательно облегчает. Плюс обязывает писать javadoc. Но есть конечно и свои нюансы. Не все кейсы покрывает, иногда приходится и руками что-то делать.

джавадок ... в смысле аннотации к классам и методам?

не аннотации, а именно джавадок. например если контроллер возвращает какой-то объект, то из джавадока к полям этого объекта либа будет получать описание полей и добавлять его в доку. аннотации тоже используются, для описания в доке ограничений на данные.

в конце статьи как я понял описан способ совместить подходы Code First (SpringAutoRestDocs) и API First (Swagger).

Рассмотрен как пример мульти-модульный проект со следущей структурой: библиотека со свагер генератором (swagger-library), стартер с swagger-ui(swagger-webjar-ui-starter), приложение которое имплементирует классы библиотеки(spring-auto-rest-docs).

Имхо, грамотно сделано, т.к. Spring Rest Docs довольно тяжел в применении и заставляет писать большое количество кода, а кодогенерация из Swagger поприятней будет.

я кстати статью что-то пропустил, не увидел что ваш вопрос к ней отсылает.

я вот про эту https://habr.com/ru/post/556400/

да, уже видел.

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

у вас в командах есть аналитики, которые занимаются документированием в т.ч. на SpringAutoRestDocs? Или это целиком вотчина разработчиков?

У меня идея фикс это совместить циклы аналитики и разработки в один. Выглядит примерно так:
1) Аналитик заводит в гите фича-ветку под описание интеграции
2) Аналитик составляет спецификацию сервиса в YAML на OpenAPI (Swagger) и выкладывает ее в гит.
3) Разработчик формирует первый вариант кодогенерации из YAML
4) Разработчик формирует заготовку на SpringAutoRestDocs и передает в аналитика. Или же аналитик делает это сам.
5) Аналитик дописывает документацию к сервису в ASCIIDOC
6) DevOps (или разработчик) публикует документацию на общем ресурсе.

Профит.

Мне понравился комментарий о том, что сваггер очень url centric и делает неудобным человекочитаемое описание

никто не мешает пользоваться разными генераторами статики. Я пользую https://github.com/Mermade/widdershins

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

очень даже неплохо имхо

согласен, что AsciiDoctor зависимые проекты дают больше гибкости в составлении спецификации.

у нас этим проектированием и документированием API занимаются разработчики. описанный вами процесс интересный, но у я тут экспертного мнения не имею. у нас аналитики в основном работают на бизнес-уровне и так глубоко в специфику не погружаются.

а можете сказать, каким? сейчас в одном проекте стоим на распутье... изначальная идея засорять код аннотациями, генерировать open api (из которого генерировать Asciidoc) и из open api кодогенерировать клиент.. разработчики говорят, сложновато и тянут в сторону Vaadin.. но мне прямо не нравится)