у JavaDoc есть точно проблемы с кириллицей в аннотациях к методам ( и да, она страшненькая

скрипт должен собирать доку не всю, а по определенному алгоритму, чтобы было юзерфрендли как в https://docs.spring.io/spring-security/site/docs/current/reference/html5/#oauth2client

Ну это практически тот же жавадок)

Я делал по другому: сиквенс рисовал руками, общие слова - руками, xsd рисовал руками.
Рядом клал svg шку с деревом схемы. Обычно выходило быстрее, чем настраивать автогенерацию.

Есть почитать подробности?
Не слышал, что бы были такие плагины или билд скрипты.

сек... уже проделывал такую штуку. Почти из коробки работает

Using Slate in Docker: https://github.com/slatedocs/slate/wiki/Using-Slate-in-Docker
Converting an OpenAPI/Swagger file to Markdown with the Widdershins CLI: https://mermade.github.io/widdershins/ConvertingFilesBasicCLI.html


1) сделано описание API путем генерации YAML в  формат Mermade/widdershins
node widdershins C:/Dev/IdeaProjects/xrg-core/bo/bo-doc/src/main/openapi/gk/xrg_bo/boserver/doc/rest/Items.yaml -o index.html.md
node widdershins --environment env.json swagger.json -o myOutput.md
node widdershins -e env.json C:/Dev/IdeaProjects/xrg-core/bo/bo-doc/src/main/openapi/gk/xrg_bo/boserver/doc/rest/Incomings.yaml -o index.html.md

2) поднят контейнер Docker для рендерелки Slate
PS C:\Dev\Git\slate> docker stop slate
PS C:\Dev\Git\slate> docker build . -t slate

3) поднят сайт с описанием API Mobile GK на Slate
PS C:\Dev\Git\slate> docker run -d --rm --name slate -p 4567:4567 -v /build:/srv/slate/build -v /source:/srv/slate/source slate
'PS C:\Dev\Git\slate> docker run -d --rm --name slate -p 4567:4567 -v C:/Dev/Git/slate/build:/srv/slate/build -v C:/Dev/Git/slate/source:/srv/slate/source slate
To build your sources while the container is running, run:
docker exec -it slate /bin/bash -c "bundle exec middleman build"

ps Однако есть проблемки с генерацией под виндой в докеровских контейнерах. Поэтому приходится делать танцы с бубном для копирования исходника.
PS C:\Dev\Git\slate> docker exec -it slate /bin/bash
root@292a6c442db4:/srv/slate# df -lh
root@292a6c442db4:/srv/slate# ls /srv/slate/source
root@292a6c442db4:/srv/slate# ls *
root@292a6c442db4:/srv/slate# exit

docker cp source/. slate:/srv/slate/source

в итоге получается вот такое чудо, пример взят из https://github.com/Mermade/widdershins

Спасибо)
Подход ясен. Немного не то, что ожидал, но многим может подойти.
Из этой же области "собрать красивый html по контракту" есть инструмент https://github.com/Redocly/redoc
Должно быть поменьше проблем: локально можно nodejs в песочнице в wsl запускать.

Но опять же: это один из вариантов презентации api, не архитектуры и не спеки на клинский сервис. Это только руками собирать.

те же яйца только в профиль. Редок смотрел, не понравился оформлением странички из коробки. )

Так то да)
Спасибо за диалог!

еще немного поисследовал и нашел как генерить нужные вещи в adoc непосредственно из исходника проекта в git

https://mrhaki.blogspot.com/2014/04/awesome-asciidoc-include-partial-parts.html

т.е. достаточно по исходнику расставить нужные метки и можно делать нарезку
при появлении новых фич попробовать проверять сонаркубом или другим инструментом покрытие исходников тегами для формирования спецификации

Мне просто интересно, а как фича может попасть в прод, если на неё нету требований и тестов? Типа "очень надо, запилите пажалусто, дадим Многа денех" ?

😁

Сарказм уловил. Но размер создаваемой задницы и её глубина от этого не меняется.

Да были требования, но настало время солюшен документ. И тут что-то пошло не так.

да довольно легко, мы живем далеко не в идеальном мире

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

Теневое IT называется, по-пацански залетает

Когда требования погоняют требованиями и бизнесу надо все вчера, то очень запросто прогнуться под Клиента и забросить документирование в долгий ящик.

Каждый день приходится рыть чей-то исходник, чтобы понять реализацию. Это больно.

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