Коллеги, привет!

Поделитесь плз опытом, мб у кого-то уже был такой кейс.

Есть продукт, у продукта есть API. Документация у продукта в Confluence, включая документацию API.
Есть мысли автоматизировать документирование API следующим образом:
1. Разработчик API в процессе пишет комменты в коде неким согласованным образом, по какому-то шаблону;
2. Дальше мы собираем эти комменты, скармливаем их какому-нибудь условному phpdoc (первое, что пришло в голову, скорее всего, есть варианты лучше);
3. Из скормленной ранее документации формируется HTML и постится в заданный раздел в Confluence.

Возможно, мы мыслим не в том направлении, и стоит делать проще)

Как вариант пойти по другому пути: https://openapi-generator.tech/docs/generators

Разработчики создают схему. Из схемы генерируются маршруты (интерфейсы контроллеров с проставленными аннотациями) и DTO-шки (те объекты которые приходят в запросе и возвращаются в ответе).

а что ещё есть? redoc?

а, ну и нам очень зашел widdershins: конвертер из OpenAPI в md

Всем привет!
Хочу поделиться с сообществом своим списком полезных русскоязычных ресурсов, связанных с ИТ.
На создание этого списка ушло немало времени, надеюсь, он вам будет полезен так же, как и мне.

#resources #awesome #list #podcasts #meetups #events #blogs

https://github.com/unchase/awesome-russian-it

Как так вышло что нету ничего про документацию?

ebanoe.it добавьте.

Спасибо, в ближайшее время добавлю

ты серьезно? Это же бессмысленный поток нытья