Выглядит как "Делайте хорошо, а нехорошо не делайте". Не хватает конкретных примеров в плане подготовки самой документации.
Не совсем понял, как при изменении API волшебным образом получится внести минимум корректировок? Добавился атрибут в API - значит скорее всего и на UI появится новый элемент, а раз он появился, значит были причины - требования, там и сам сценарий мог измениться. Я к тому, что не всегда все так просто и гладко и цепная реакция чаще всего срабатывает.
Вопрос в самих средствах обработки документации. Пользуйтесь IDE, уж про рефакторинг связанных документов всегда напомнит и даже может сделать за вас, если include файлик переехал в другое место.
API Swagger - для Java BE есть spring openApi либа. Пишут аннотацию и реализация AS IS всегда под рукой, без танцев с бубнами. Аналитики также могут выгружать эту спеку и дорабатывать ее, в той же IDE.
Раз в месяц проводите быстрый аудит документации
Я даже представить боюсь, как у вас "быстро" может быть проверена вся документация раз в месяц.
Судя по всему я слишком глуп и неопытен в подобных программах, чтобы справиться с облегченной версией. Скопировал example-config.json из source пака, потому что в singbox-launcher-0.2.5-win64.zip его не было. Переименовал в нужный config, скопировал свою ссылочку на vless, которую в nekoray использую, скачал exe и dll в лаунчере, запустил....и Crash sing-box с ретраями.
Поставил автору плюс - это безусловно. Вот только бы из коробки чтобы работало, там по самым стандартным направлениям в РФ :(
Детально в use case описывать реализацию на этапе BA - ну такое себе
Спецификация полей (обычно называют спекой FE), фильтров, их доступности и обязательности предпочитаю выносить в отдельный документ и его вставлять уже в нужные сценарии по блокам.
Раз беретесь описывать ошибки, описывайте и валидации если они требуются, но это часть СА
В каждой компании да и даже в каждой команде все пишут по своему, как удобно им. Мне как СА достаточно просто самого бизнес процесса, нужного атрибутивного состава, который хочет бизнес и примерного макета согласованного, ибо БА или дизайнер может не знать (и не должен) всех технических нюансов.
Описание поведения фронта (плейсхолдеры, иконки и прочее) все есть на макете - в вашей документации это читать излишне, тем более, что это дефолтное поведение.
Резюмирую - не плохо, а избыточно, что ведет в перспективе к бОльшим затратам по времени и сложности поддержания в актуальном виде (все это имхо, из собственного опыта)
p.s. сводит скулы от таблиц конфлюенса и изображениях в ячейках
Не совсем понятно, почему в вашей компании решили описывать API по-человечески в сваггере только к 2025 году. Как будто бы надо было очень как раньше.
Также настоятельно рекомендую покопать документацию и синтаксис сваггере поглубже, чем базовый, описанный вами.
allOf для объектов с наследованием
различные типы данных в schema помимо application/json. Можно по факту и '*/*' указать. Но если различные типы данных могут отдаваться, то лучше явно указать + работает адекватно форматирование для json/xml
если уже и так дружите с GIT, то посмотрите в сторону плагина в IntelIjIdea (OpenApi (Swagger) Editor). Из плюсов - в миллион раз удобнее чем веб редактор с автокомплитом и всеми встроенными средствами разработки. Из минусов - превью руками надо обновлять и может чутка подтормаживать при огромном количестве строк.
На практике обычно всё сводится к карточке в Jira. Достаточно добавить простое описание и этого хватит, чтобы команда поняла суть и начала работать
Потом искать описание в задачах. Соболезную коллегам через пару месяцев
Отдельная красота, если доработка будет с API. Если сразу все в таске писать явно руками, без вложений сваггера, прям от одной мысли больно. Если нужно сделать ручку, скорректировать DTO какие нибудь
Я работаю на Python и не хотела распыляться на технологии, которые знаю поверхностно
Подготовка к техническим интервью. Чаще всего нужно освежить в памяти - Python: типы данных, конструкции языка, принципы оптимизации кода
...Вообще, для автоматизации тестирования глубокого знания Python не нужно. Но меня начали спрашивать именно углубленные вопросы по Python, типы данных, конструкции языка
Для всех выпускников, которые только после учебного заведения пришли в IT, ждущие 300кк\наносек, или вкатуны-накрутчики, желающие того же и не ценящих свои комфортные условия - желаю им всем пойти поработать в продажи, особенно холодные, в тех поддержке им слишком кайфово будет. На контрасте быстро почувствуют разницу и вкус жизни
Для PlantUML есть еще варианты, такие как плагин для IDE (Idea, Vscode) или вариант с Notepad ++ (потребуется дополнительно установить Java на машину), но оба варианта позволяют не лезть лишний раз в браузер
это как пример. POST можно, просто так не нужно) получить данные можно и через DELETE (можно != нужно)
Выглядит как "Делайте хорошо, а нехорошо не делайте". Не хватает конкретных примеров в плане подготовки самой документации.
Не совсем понял, как при изменении API волшебным образом получится внести минимум корректировок? Добавился атрибут в API - значит скорее всего и на UI появится новый элемент, а раз он появился, значит были причины - требования, там и сам сценарий мог измениться. Я к тому, что не всегда все так просто и гладко и цепная реакция чаще всего срабатывает.
Вопрос в самих средствах обработки документации. Пользуйтесь IDE, уж про рефакторинг связанных документов всегда напомнит и даже может сделать за вас, если include файлик переехал в другое место.
API Swagger - для Java BE есть spring openApi либа. Пишут аннотацию и реализация AS IS всегда под рукой, без танцев с бубнами. Аналитики также могут выгружать эту спеку и дорабатывать ее, в той же IDE.
Я даже представить боюсь, как у вас "быстро" может быть проверена вся документация раз в месяц.
Судя по всему я слишком глуп и неопытен в подобных программах, чтобы справиться с облегченной версией. Скопировал example-config.json из source пака, потому что в singbox-launcher-0.2.5-win64.zip его не было. Переименовал в нужный config, скопировал свою ссылочку на vless, которую в nekoray использую, скачал exe и dll в лаунчере, запустил....и Crash sing-box с ретраями.
Поставил автору плюс - это безусловно. Вот только бы из коробки чтобы работало, там по самым стандартным направлениям в РФ :(
Пару вопросов:
Зачем так усложнять, если можно не усложнять?
Детально в use case описывать реализацию на этапе BA - ну такое себе
Спецификация полей (обычно называют спекой FE), фильтров, их доступности и обязательности предпочитаю выносить в отдельный документ и его вставлять уже в нужные сценарии по блокам.
Раз беретесь описывать ошибки, описывайте и валидации если они требуются, но это часть СА
В каждой компании да и даже в каждой команде все пишут по своему, как удобно им. Мне как СА достаточно просто самого бизнес процесса, нужного атрибутивного состава, который хочет бизнес и примерного макета согласованного, ибо БА или дизайнер может не знать (и не должен) всех технических нюансов.
Описание поведения фронта (плейсхолдеры, иконки и прочее) все есть на макете - в вашей документации это читать излишне, тем более, что это дефолтное поведение.
Резюмирую - не плохо, а избыточно, что ведет в перспективе к бОльшим затратам по времени и сложности поддержания в актуальном виде (все это имхо, из собственного опыта)
p.s. сводит скулы от таблиц конфлюенса и изображениях в ячейках
Премного благодарен за статью. Очень интересно было почитать!
Не совсем понятно, почему в вашей компании решили описывать API по-человечески в сваггере только к 2025 году. Как будто бы надо было очень как раньше.
Также настоятельно рекомендую покопать документацию и синтаксис сваггере поглубже, чем базовый, описанный вами.
allOf для объектов с наследованием
различные типы данных в schema помимо application/json. Можно по факту и '*/*' указать. Но если различные типы данных могут отдаваться, то лучше явно указать + работает адекватно форматирование для json/xml
если уже и так дружите с GIT, то посмотрите в сторону плагина в IntelIjIdea (OpenApi (Swagger) Editor). Из плюсов - в миллион раз удобнее чем веб редактор с автокомплитом и всеми встроенными средствами разработки. Из минусов - превью руками надо обновлять и может чутка подтормаживать при огромном количестве строк.
все API в сваггере MUST HAVE + техническое описание сценариев с конкретной логикой, где, какая ручка, какой фильтр.
Потом искать описание в задачах. Соболезную коллегам через пару месяцев
Отдельная красота, если доработка будет с API. Если сразу все в таске писать явно руками, без вложений сваггера, прям от одной мысли больно. Если нужно сделать ручку, скорректировать DTO какие нибудь
чисто мем:
Я работаю на Python и не хотела распыляться на технологии, которые знаю поверхностно
Подготовка к техническим интервью. Чаще всего нужно освежить в памяти -
Python: типы данных, конструкции языка, принципы оптимизации кода
...Вообще, для автоматизации тестирования глубокого знания Python не нужно. Но меня начали спрашивать именно углубленные вопросы по Python, типы данных, конструкции языка
прочитав статью наискосок, сдается мне, что ИИ не закрылась вплоть до публикации статьи
Для всех выпускников, которые только после учебного заведения пришли в IT, ждущие 300кк\наносек, или вкатуны-накрутчики, желающие того же и не ценящих свои комфортные условия - желаю им всем пойти поработать в продажи, особенно холодные, в тех поддержке им слишком кайфово будет. На контрасте быстро почувствуют разницу и вкус жизни
вы просто не распробовали корейский игропром. Годная игра (если оттуда выпилить точки и ограничения) :)
сама иконка проекта и в хедере, я об них. Тот самый медвед
за медведа конечно плюс, выглядит гармонично там :)
Спасибо за подробную и полезную статью с примерами
как человек очень далекий от Линуха, кажется, что лучше поставить проверенный Ubuntu?
Для PlantUML есть еще варианты, такие как плагин для IDE (Idea, Vscode) или вариант с Notepad ++ (потребуется дополнительно установить Java на машину), но оба варианта позволяют не лезть лишний раз в браузер
выглядит неплохо, любую штуку, которую можно вкорячить в PlantUml сразу плюсую :)
Но есть пару вопросов:
Применяете ли это в практике на ИРЛ проектах?
Если да, то в каком случае? (для описания таблиц есть более простые и изящные способы - от конфлюенса и простого asciidoc\MD если DocsAsCode)
Если это все таки применяется в рамках прода (и в DocsAsCode), то, версия документа, кажется излишней
Как пользователь поймет связь с другими таблицами БД? Напрашивается еще один столбец на какую таблицу ссылаться (чтобы руками не мусорить в комментах)
Пробовали ли натягивать это на пайплайн изменений в БД? Чтобы таблица формировалась автоматически из реализации?
возраст это всего лишь цифра, просто надо подтянуть знания и дерзать. Все возможно
наберут таких манагеров и получается потом, что двое пашут, а семеро руками машут