Size: a a a

Архитектура ИТ-решений

2020 August 28

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Vlad
Видел плагины которые выковыривают javadoc и формируют подраздел в adoc. Проблема в людях: JavaDoc неказистые мануалы отразработчиков разработчикам.

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

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

V

Vlad in Архитектура ИТ-решений
Andrew Nilove 💔
например, тот же spotify рендерит живые файлы проекта и дока создана на 90% автогенеренкой

https://developer.spotify.com/documentation/web-api/reference-beta/
Ну это практически тот же жавадок)

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

V

Vlad in Архитектура ИТ-решений
Andrew Nilove 💔
но у Spotify случай попроще, т.к. они генерят на основе уже готовых Swagger файлов
Есть почитать подробности?
Не слышал, что бы были такие плагины или билд скрипты.
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Vlad
Есть почитать подробности?
Не слышал, что бы были такие плагины или билд скрипты.
сек... уже проделывал такую штуку. Почти из коробки работает
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Vlad
Есть почитать подробности?
Не слышал, что бы были такие плагины или билд скрипты.
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
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
в итоге получается вот такое чудо, пример взят из https://github.com/Mermade/widdershins
источник

V

Vlad in Архитектура ИТ-решений
Andrew Nilove 💔
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
Спасибо)
Подход ясен. Немного не то, что ожидал, но многим может подойти.
Из этой же области "собрать красивый html по контракту" есть инструмент https://github.com/Redocly/redoc
Должно быть поменьше проблем: локально можно nodejs в песочнице в wsl запускать.

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

AN

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

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

V

Vlad in Архитектура ИТ-решений
Andrew Nilove 💔
те же яйца только в профиль. Редок смотрел, не понравился оформлением странички из коробки. )
Так то да)
Спасибо за диалог!
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Vlad
Видел плагины которые выковыривают javadoc и формируют подраздел в adoc. Проблема в людях: JavaDoc неказистые мануалы отразработчиков разработчикам.

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

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

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

AL

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

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

AL

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

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Alexander Luchkov
Мне просто интересно, а как фича может попасть в прод, если на неё нету требований и тестов? Типа "очень надо, запилите пажалусто, дадим Многа денех" ?
😁
источник

AL

Alexander Luchkov in Архитектура ИТ-решений
Сарказм уловил. Но размер создаваемой задницы и её глубина от этого не меняется.
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Да были требования, но настало время солюшен документ. И тут что-то пошло не так.
источник

S

Sebor in Архитектура ИТ-решений
Alexander Luchkov
Мне просто интересно, а как фича может попасть в прод, если на неё нету требований и тестов? Типа "очень надо, запилите пажалусто, дадим Многа денех" ?
да довольно легко, мы живем далеко не в идеальном мире
источник

AL

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

VU

Vitaly U in Архитектура ИТ-решений
Alexander Luchkov
Мне просто интересно, а как фича может попасть в прод, если на неё нету требований и тестов? Типа "очень надо, запилите пажалусто, дадим Многа денех" ?
Теневое IT называется, по-пацански залетает
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Alexander Luchkov
Не, мне понятно, но есть же история про "возьмём тут в долг, а потом будем платить по нему проценты". Известная же штука. Или всякий там солюшндок это способ типа закрыть техдолг?
Когда требования погоняют требованиями и бизнесу надо все вчера, то очень запросто прогнуться под Клиента и забросить документирование в долгий ящик.

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

AL

Alexander Luchkov in Архитектура ИТ-решений
Andrew Nilove 💔
Когда требования погоняют требованиями и бизнесу надо все вчера, то очень запросто прогнуться под Клиента и забросить документирование в долгий ящик.

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