Дисклеймер. Это бесстыдная реклама и самопиар. И еще циничный байт на донаты. Тем, кого от такого корёжит можно дальше не читать.
Дисклеймер 2. Мне надо решить развивать или проект или закопать. Проект далек от идеала, но надеюсь, что уже достаточно готов, чтобы приносить реальную пользу.
Я сделал расширение для хрома, чтобы документировать сваггер спецификации. Полезно для ситуаций, когда код уже написан и используется, а на описание API не хватает ресурсов. По задумке должно экономить тонны тупого монотонного ручного труда. Попробовать воспользоваться можно здесь. Код лежит здесь.
Update 15.07.25. По просьбам комьюнити сделал одностраничник, пока тот же билд что и расширение, поэтому выглядит кривовато. Попробовать веб-версию
Как пользоваться
Простой кейс (все описания живут в одном файле)
1) Установить расширение
2) На страничке Swagger UI скачать JSON или YAML файл со спецификацией
3) Загрузить сохраненный файл спецификации по кнопке "Выбрать файл". Для Windows и MacOS загрузка файла работает нормально. На линуксе расширение теряет фокус и закрывается при загрузке файла. Чтобы расширение не закрывалось на линуксе и файл загружался, нужно снчала открыть devtools расширения
4) Нажать кнопку "Конвертировать" и получить файл swagger.docx со спецификацией
5) Profit!
Сложный кейс
Бывает так, что описания собираются по кусочкам из нескольких файлов, в ссылке на странице Swagger UI спецификация не целиком
1) Установить расширение
2) Зайти на страницу Swagger UI, дождаться пока он прогрузится целиком
3) Нажать кнопку "Создать документацию" и получить файл swagger.docx со спецификацией
4) Profit!
Кейс сложнее, несмотря на меньшее количество действий, потому что под капотом там надо сначала собрать воедино кусочки спецификации, что менее надежно и более подвержено ошибкам.
FAQ
Зачем публиковать сырой продукт? Тебе не стремно выкладывать такую недоделанную фигню?
Выкладывать стремно, но не выкладывать ещё более стремно. Внутренняя мотивация у меня на данный момент иссякла, а реальной или потенциальной пользы в продукте достаточно, чтобы комьюнити мне помогло бустануть эту самую мотивацию. Ну а если я неправ насчет пользы, то тогда смогу закопать проект со спокойной душой.
А вот тут есть штуковина, делающая то же самое, только лучше, что на это скажешь?
Если правда есть, и правда лучше, то замечательно! Поставлю ссылки на нее везде где смогу и пусть люди пользуются ей.
Почему итоговый формат именно такой? Есть ли возможность его поменять?
Это самый частый формат, который лично я встречал в работе. После консультаций с коллегами аналитиками решил остановиться именно на нем. Сейчас возможности менять формат итогового документа нет, но я вижу возможность добавить такую фичу в будущем если проект будет развиваться
У меня не сработало или сработало криво. Но если это поправить, то я буду пользоваться. Что можно сделать?
Можно создать issue. Не запрещается даже сделать собственный ПР с фиксом. Гарантировать ничего не могу, но заинтересованность комьюнити в продукте увеличивает мою заинтересованность в его развитии.
Как лучше оставлять фидбек?
Общий фидбек можно прямо здесь в комментариях. Фича реквесты и баг репорты в гитхабе У донатов тоже есть поле комментарий, этот способ мне приятнее других, но он не единственный и не обязательный.
Планируешь дальше развивать продукт?
Очень сильно зависит от реакции комьюнити на продукт. Чем плюсовее будет вайб, тем выше вероятность что буду.
Ты вообще как‑то тестировал, прежде чем выкладывать? Как можно было пропустить такой очевидный косяк как Х?
Как‑то тестировал, видимо Х не попал в мои тестовые данные или не попался мне на глаза. Или хуже того я о нем знаю, но не счел рациональным его фиксить на данном этапе.
Это же всё чтобы просто поклянчить деньги за свою поделку?
Безусловно! Но не только, я ещё хочу набрать фанатичную армию преданных поклонников, готовых по первому моему слову на всякие безрассудства.
Ты откуда такой дерзкий?
Из Тольятти, со старого города.