Comments 14
Вопрос "зачем" не раскрыт
Можно ли оформить проект просто как одностраничник, без всяких расширений?
и второе что ваш проект делает, по описанию он должен делать документацию
на картинках я не увидел ничего кроме того что ваше расширение сделало из обычной сваггер документации сваггер в браузере, так эту работу и сам сваггер в силах выполнить, покажите пример готовой документации которую уже сгенерировали вы.
Да можно оформить в одностраничник. Описание итогового формата добавлю спасибо за совет. Расширение решил сделать из-за сложного кейса, где сваггер сшивается из кусочков и в скачиваемом файле только ссылки на определения компонентов. Его одностраничник решать не сможет, но для простых вполне сойдет.
Зачем это всё когда есть автогенераторы документации? Scribe прекрасно генерирует документацию с Try It и Postman коллекцией.
Я честно попробовал, но даже по инструкции ничего не получилось.
В статье нет примера результата. Оценить качество документации, которую подготавливает инструмент не получилось.
Формат docx широко распространён в узком кругу опрошенных. Хранить доку в docx это лет 15-20 назад было базой. Сейчас - кто во что горазд. Я например, продвигаю doc as code и пишу на markdown. Может имеет смысл присмотреться к другим форматам...
Вообще, openApi и swagger вполне достаточны для документирования. Примеры есть, подёргать можно. В дополнительном описании эндпоинтов может быть описана системная логика. Но вы такое описание из свагера не вытащите, это не возможно. Тогда встаёт вопрос: кто потребитель вашей документации и для чего она вообще нужна?
В развитых проектах, в отличии от "наколеночной разработки", сначала готовится документация, а потом пишется код. И опять таки встаёт вопрос: кто потребитель вашего инструмента, для кого вы его хотите сделать?
Ну и конкуренция с ИИ. Сейчас модели вполне сносно готовят документацию по эндпоинтам проходясь по коду и вытаскивая всю подноготную из системной логики.
Возможно, есть процессы, в которых данный инструмент будет полезен. Тогда, для продолжения работы, необходимо понимать, что это за процессы, как этот инструмент будет встроен в процесс и какие артефакты будет готовить и как будет их обновлять. Определится с тем, кто является потребителем самого инструмента и кто является потребителем результата его работы. И спросить не у всего сообщества (слишком широкий охват и большой процент нецелевой аудитории) а именно тех, для кого этот инструмент будет полезен.
Спасибо за фидбек и советы. Моя цель как раз по реакции всего комьюнити понять перспективы моей поделки. Перспективность буду вычислять на основе абсолютных величин заинтересованных людей, так что чем больше охват, тем больше шансы.
1. Тут не знаю напишу в личку.
2. скрины примеров ответов добавил.
3. Возможно стоит, я не аналитиик, что сейчас является последним словом техники не знаю. Если найдутся заинтересованные люди то в процессе общения с ними может и выясним. Docx потому что видел такое у коллег, с которыми proof-of-concept обсуждал и потому что знаю как с ним работать.
4-5. Меня идея посетила на одном из дейли моего прошлого проекта, когда обсуждалим найм стажеров-аналитиков в ключе "вот классно если бы они актуализировали аналитику по сваггер контрактам". То есть ситуация спустя год с лишним разработки пришла к тому, что в код изменения вносятся, а в описания сущностей в документации нет. Потому что это очень трудозатратно, а аналитики заняты проработкой новых фичей. Контора большая и разработка там супер бюрократизированная, для вот таких случаев может пригодиться на мой взгляд.
6. Полностью согласен насчет возможностей ИИ в этом вопросе. Фокус-группа у меня была маленькая, порядка 10 человек, но из них никто про ИИ в этом вопросе не заикнулся.
Однозначно лучше закопать проект.
Круто, мне как раз такое надо)
Я "уже" документирую вручную.
К сожалению автогенерация не учитывает всех нюансов DTOх, типа сериалайзеров и т.д.
Сваггер это и есть документация. Смысл из него ещё что то днлать ? Ваш плагин просто меняет формат. Облегчает работу техничесеог пимателя, возможно. Но для пользователей апишеи интерактивный сваггер полезней текстового документа.
Идея отличная. Хорошо бы зашла. Лет N назад. Пару недель назад мне нужно было взять из сваггера json schema для API чужого сервиса и превратить его в доку в confluence и pydantic class моего приложения, из которого к этому api подключаться. Мне помог deepseek. Я его просто попросил сконвертировать. Именно так это работает и должно работать в 2025 году
Я бы например просто скачал файл opeapi.json и прикрепил к документу в базе знаний или к репозиторию в git.
Хотя тут есть нюанс с индексацией - искать по базе знаний было бы не очень удобно. Тут можно было бы рассмотреть создание какого-то конвертера в тот формат, в котором реализована база знаний.
А вот в documentation as a code github отлично справится с поиском по openapi.json для поиска операции и ее параметров.
Вы все еще документируете сваггер спецификации вручную? Тогда мы идем к вам