Дисклеймер. Это бесстыдная реклама и самопиар. И еще циничный байт на донаты. Тем, кого от такого корёжит можно дальше не читать.
Дисклеймер 2. Мне надо решить развивать или проект или закопать. Проект далек от идеала, но надеюсь, что уже достаточно готов, чтобы приносить реальную пользу.
Я сделал расширение для хрома, чтобы документировать сваггер спецификации. Полезно для ситуаций, когда код уже написан и используется, а на описание API не хватает ресурсов. По задумке должно экономить тонны тупого монотонного ручного труда. Попробовать воспользоваться можно здесь. Код лежит здесь.
Как пользоваться
Простой кейс (все описания живут в одном файле)
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. Не запрещается даже сделать собственный ПР с фиксом. Гарантировать ничего не могу, но заинтересованность комьюнити в продукте увеличивает мою заинтересованность в его развитии.
Как лучше оставлять фидбек?
Общий фидбек можно прямо здесь в комментариях. Фича реквесты и баг репорты в гитхабе У донатов тоже есть поле комментарий, этот способ мне приятнее других, но он не единственный и не обязательный.
Планируешь дальше развивать продукт?
Очень сильно зависит от реакции комьюнити на продукт. Чем плюсовее будет вайб, тем выше вероятность что буду.
Ты вообще как‑то тестировал, прежде чем выкладывать? Как можно было пропустить такой очевидный косяк как Х?
Как‑то тестировал, видимо Х не попал в мои тестовые данные или не попался мне на глаза. Или хуже того я о нем знаю, но не счел рациональным его фиксить на данном этапе.
Это же всё чтобы просто поклянчить деньги за свою поделку?
Безусловно! Но не только, я ещё хочу набрать фанатичную армию преданных поклонников, готовых по первому моему слову на всякие безрассудства.
Ты откуда такой дерзкий?
Из Тольятти, со старого города.
Комментарии (7)
vadimchelnik
14.07.2025 06:16Можно ли оформить проект просто как одностраничник, без всяких расширений?
и второе что ваш проект делает, по описанию он должен делать документацию
на картинках я не увидел ничего кроме того что ваше расширение сделало из обычной сваггер документации сваггер в браузере, так эту работу и сам сваггер в силах выполнить, покажите пример готовой документации которую уже сгенерировали вы.
SeeeRgo Автор
14.07.2025 06:16Да можно оформить в одностраничник. Описание итогового формата добавлю спасибо за совет. Расширение решил сделать из-за сложного кейса, где сваггер сшивается из кусочков и в скачиваемом файле только ссылки на определения компонентов. Его одностраничник решать не сможет, но для простых вполне сойдет.
radioIT
14.07.2025 06:16Зачем это всё когда есть автогенераторы документации? Scribe прекрасно генерирует документацию с Try It и Postman коллекцией.
DMS_13
14.07.2025 06:16Я честно попробовал, но даже по инструкции ничего не получилось.
В статье нет примера результата. Оценить качество документации, которую подготавливает инструмент не получилось.
Формат docx широко распространён в узком кругу опрошенных. Хранить доку в docx это лет 15-20 назад было базой. Сейчас - кто во что горазд. Я например, продвигаю doc as code и пишу на markdown. Может имеет смысл присмотреться к другим форматам...
Вообще, openApi и swagger вполне достаточны для документирования. Примеры есть, подёргать можно. В дополнительном описании эндпоинтов может быть описана системная логика. Но вы такое описание из свагера не вытащите, это не возможно. Тогда встаёт вопрос: кто потребитель вашей документации и для чего она вообще нужна?
В развитых проектах, в отличии от "наколеночной разработки", сначала готовится документация, а потом пишется код. И опять таки встаёт вопрос: кто потребитель вашего инструмента, для кого вы его хотите сделать?
Ну и конкуренция с ИИ. Сейчас модели вполне сносно готовят документацию по эндпоинтам проходясь по коду и вытаскивая всю подноготную из системной логики.
Возможно, есть процессы, в которых данный инструмент будет полезен. Тогда, для продолжения работы, необходимо понимать, что это за процессы, как этот инструмент будет встроен в процесс и какие артефакты будет готовить и как будет их обновлять. Определится с тем, кто является потребителем самого инструмента и кто является потребителем результата его работы. И спросить не у всего сообщества (слишком широкий охват и большой процент нецелевой аудитории) а именно тех, для кого этот инструмент будет полезен.
SeeeRgo Автор
14.07.2025 06:16Спасибо за фидбек и советы. Моя цель как раз по реакции всего комьюнити понять перспективы моей поделки. Перспективность буду вычислять на основе абсолютных величин заинтересованных людей, так что чем больше охват, тем больше шансы.
1. Тут не знаю напишу в личку.
2. скрины примеров ответов добавил.
3. Возможно стоит, я не аналитиик, что сейчас является последним словом техники не знаю. Если найдутся заинтересованные люди то в процессе общения с ними может и выясним. Docx потому что видел такое у коллег, с которыми proof-of-concept обсуждал и потому что знаю как с ним работать.
4-5. Меня идея посетила на одном из дейли моего прошлого проекта, когда обсуждалим найм стажеров-аналитиков в ключе "вот классно если бы они актуализировали аналитику по сваггер контрактам". То есть ситуация спустя год с лишним разработки пришла к тому, что в код изменения вносятся, а в описания сущностей в документации нет. Потому что это очень трудозатратно, а аналитики заняты проработкой новых фичей. Контора большая и разработка там супер бюрократизированная, для вот таких случаев может пригодиться на мой взгляд.
6. Полностью согласен насчет возможностей ИИ в этом вопросе. Фокус-группа у меня была маленькая, порядка 10 человек, но из них никто про ИИ в этом вопросе не заикнулся.
tzlom
Вопрос "зачем" не раскрыт