Все верно и не удивительно что слышали больше о swagger — он давно на рынке и широко используется, и он охватывает 25 языков программирования (генерация кода), теперь он мигранул в OpenAPI3.0, в ближайшие годы именно это название будет звучать вместо swagger.
SpringRestDocs относительно недавнее свежее решение и его удобно использовать в spring экосистеме, в то время как OpenAPI3.0 применим везде (но без TDD).
Отсюда и диспропорция — во времени существования продуктов, охвата языков.
Пока нет «серебряной пули»

Если Вы используете maven — все описанное актуально. Чем мне нравится спринговая документация docs.spring.io/spring-restdocs/docs/current/reference/html5 — в ней приведены конфиги для gradle/maven более того, конкретно для springrestdocs также есть примеры тестов с использованием MockMvc/RestAssured. Что юзать — Ваше предпочтение или специфика проекта, команды, организации.

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

Здесь речь идет не только о просмотре REST API, а о гарантированности его соответствия, написания тестов, кастомизации документации, включении в неё диаграмм, ресурсов, генерации офлайн мультиформатных версий.

Это нереально включить в одну статью (она будет перегружена материалом), поэтому, если тема будет пользоваться интересом — я однозначно опишу в следующих частях все перечисленные плюшки и разберу их на практических примерах.

Это очень хороший вопрос, на самом деле, я специально не делал в этой статье сравнение со swagger либо другим инструментом документирования, чтобы не показаться необъективным, основная идея была сделать ознакомление с TDD и springrestdocs.

В двух словах об отличиях:
springrestdocs

• генерит документацию из тестов, в случае её несоответствия логике приложения вы получаете мгновенную реакцию — падающие тесты с детальным сообщением о разнице. Т.е. гарантируется целостность
• Также формат asciidoc позволяет вести документацию в гибком формате удобном для нас (включение ресурсов, добавление текстовых секция либо файлов из classpath, переформатирование в pdf, epub и прочие), мы не ограничены стандартной страничкой свагера
• Вы вводите методологию работы по Test Driven Documentation подходу (модификация классического TDD). Вы и Ваши коллеги будете писать больше тестов, по началу будет определённый переломный период адаптации у людей в команде, которые раньше не «особо часто» применяли тесты. Но через небольшое число итераций они уже подсознательно будут работать по TDD не только при написании REST эндпоинтов, но и в остальных аспектах разработки

springfox

• необычайно легок в применении, удобен для поднятия свагера в spring-based проекте (минимум усилий).
• Springfox-swagger2 создает дополнительный json-эндпоинт спецификации и, если подключен springfox-swagger-ui, то и страничку swagger документации.
  Кстати, можете посмотреть в github моем github repo также лежит пример с использованием springfox.

Я не евангелист/адвокат какой либо из технологий, как профессионалы, мы должны знать и уметь применить нужный инструмент к нужной прикладной задаче. Всё зависит от Вашего частного случая, если вы работаете в spring экосистеме сюда идеально вписывается spirngrestdocs.

Но если у вас полиглотная система — например есть симбиоз микросервисов на spring, node, python либо других языках, то есть смысл конечно же использовать единый стандарт для их документирования — swagger, это невероятно мощный инструмент. К тому же сваггер позволяет генерировать сервервный/клиентский код, стабы исходя из файла спецификации. И здесь Вам стоит посмотреть на его новую версию OpenAPI3.0 в которой наконец появились новые фичи такие как документирование HATEOAS.

Можете посмотреть мой доклад — он больше построен на сравнение swagger со spring-rest-docs TDD with SrpingRestDocs