Спасибо за рассказ! Было интересно посмотреть, потому что документирую REST API в Confluence (тех.писатель). На 90% вручную, оставшиеся 10% - спасают придуманные со временем шаблоны. Описание для внешних читателей. Сносно, но много ручной работы и дисциплины уходит. =) Даем описание параметров (простые таблицы без вложенности) + примеры в cURL/JSON. На встраивание Swagger в Confluence не договорились с разработкой и безопасниками. Единственный момент "интерактивности" - написал от руки и выложил JSON-коллекции, чтобы целевой аудитории не нужно было копипастить примеры в Postman. Изначально использую "объемную" структуру с кучей перекрестных ссылок. Подумывал сделать one-page API reference (тем же page include), потому что вроде как разрабам это удобнее просматривать через CTRL+F. Но вот послушал про то, что "конф не откроет" большое описание - прям сомнения появились, надо ли.
Если аналитик/техпис сразу пишет yaml под разработку, то можно вставлять фрейм и не париться с таблицей. Если безопасники закрыли этот вариант, то стоит спросить их про возможность развернуть шаблон апи в отдельном сервисе на тестовой среде. Без возможности прокидывать запросы в боевую бд, только в тестовую среду с шаблонами ответов. Но тут два вопроса. Первый - про возможность в фрейм вставлять только один метод. Второй - доступ в конфу не так просто дать даже internal сервису. У нас не вышло.
Олег, здравствуйте!) большое спасибо за лекцию, очень ценная информация) Подскажите, пожалуйста, как реализовать СА если есть сценарий с ошибкой. Например есть запрос, мы идём в смежную систему, по какой то причине смежная система отвечает ошибкой, * какой то процесс*, на стороне клиента видим ошибку. Такой вариант надо описывать на другой странице с новой схемой? Или это можно как то засунуть на эту же страницу? Или все собирать на одной странице это плохая практика? Ещё вопрос, как указывать описание систем логирования, мониторинга и тд?
Если надо описать процесс обработки ошибки, которую выдаёт внешняя система, то можно конечно нарисовать схему. Другой вопрос, что таких ошибок может быть много и на каждую схему не нарисуешь. Значит здесь нужно описать общий подход. Например, "Если внешняя система отвечает с ошибкой, то приложение должно ответить с ошибкой, завернув текст и код ошибки смежной системы в тело ответа". Как заворачивать подобные ошибки каждая команда решает сама. Тут подходы разнятся и надо уточнять у ваших разработчиков. Главное знать в каком поле вернётся внешняя ошибка и её код (если он есть), а также какой код будет сформирован вашим приложением. Тогда ошибка будет читаема и причина будет светиться в логах и внешний сервис будет знать о ней. Порой внешний сервис не должен знать о внутренней кухне (что у вас и где у вас пошло не так). Пользователь точно не должен про это знать, т.е. на фронте эта ошибка должна преобразовываться в человеческий текст с причиной ошибки. Где описывать ошибки внешнего сервиса? Они должны быть описаны на стороне того сервиса. Разработчику можно прикрепить ссылку на их документацию. Он в целом обычно делает алгоритм сразу на группу кодов: "если получил 400, запиши причину из этого поля ответа внешней системы в это поле ответа, код прокинь сюда, скопируй http status code и выплюнь наружу". Обычно подобное поведение прописывается дефолтно в стандартах разработки API вашего отдела. Их запаришься писать в каждом сервисе, а так один раз договорились и весь флот API работает в рамках одной модели поведения. Порой надо описать нетривиальное поведение для конкретных ответов внешней системы. Например, при ошибке от внешней системы надо откатить транзакцию, или повторить запрос с таймаутом, либо пожаловаться в мессенджер и так далее. Можно также явно приписать поведение для http status code или кодов бизнес-ошибок. Так, если объект уже создан, то это считать ошибкой уже не надо, наружу можно отдать соответствующий код. Либо, если сценарий длинный, то указать, что эта ошибка не прерывает выполнение запроса и алгоритм идёт дальше.
На уровне документа технического решения в списке нефункциональных требований можно отметить логирование и мониторинг. Если система новая и люди "ни в зуб ногой" что в логировать, то можно явно прописать (но это выглядит больше как работа разработчика). В том числе можно указать требование к наличию трассировочного идентификатора. Мониторинг зачастую надо явно прописывать в НФТ: какие метрики нас интересуют, за какой срок, в какой момент слать алерты, границы памяти приложения, места на диске, нагрузки, нужен ли дашборд и так далее. Это отдельная большая тема.
Изменения формируются сперва в виде требований в meeting notes, далее переходят в jira task (таска может сразу появиться в JIRA от заказчика). В рамках работы аналитика над задачей, обновляется документация и передаётся в разработку. Документация должна отчасти показывать ход мысли разработки. Новые поля добавляются и окрашиваются зелёным цветом. Желательно добавить комментарий в описание, почему поле было добавлено. со временем (после обновления, например, когда очередная фича зашла или спустя n недель) зелёная закраска убирается. Удаляемые поля не уходят из документации, но зачёркиваются и закрашиваются серым, добавляет комментарий кто и почему убрал поле. Есть альтернативный путь с документацией напрямую в yaml.
@@systemsengineering круто, спасибо. Как раз сейчас с командой решаем, как вести изменения при доработках API. Пока выбираем между: 1) Добавление цветом. 2) Версионирование с помощью scroll plugin. Создание branch страницы и ссылка на неё в Jira или большое ТЗ в confluence. 3) Каждое изменение описывать на отдельной странице, потом переносить в общую документацию.
@@kudriashov Это проблема. В одной из компаний я пользовался в конфлюенс плагином для контроля версий, но он быстро перегружал страницу и начинались лаги и зависания. Надо для себя решить, как часто будет обновляться документация API. Если обновляться будет часто и много, то лучше использовать git + yaml, без документации в конфлюенсе. Тут важно учесть, что никому постороннему это API читать не нужно будет (git всё-таки должен быть закрыт). Соединение нескольких страниц - это реальная боль, так как изменения вносить долго, легко запутаться, перегружается иерархия страниц. Можно спеку API вести отдельным файлом и крепить к доке, раньше для этого использовали таблицы excel. Но кажется самое простое (и с другой стороны сложное, т.к. нужны навыки) - это вести API в yaml + документацию по начинке, без указания контракта. Т.е. получил запрос из метода GET /.../.../... (смотри YAML), дальше описываешь обработку этого запроса, в конце указываешь какие данные в какие поля улетают. Иначе придётся вести таблицу полей запросов как в конфе, так и в YAML. Другими словами весь контракт в ямле, история в гите, а как это всё работает внутри сервиса - в конфлюенсе. Только не надо дублировать контракт в конфе, иначе получится двойная работа и могут появиться расхождения. Но придётся учить как создавать YAML. Ну и есть другие протоколы передачи данных, для которых yaml не подходит.
Обычно я рекомендую читать Карла Вигерса "разработка требований к программному обеспечению" и проходить бесплатные курсы на курсере школы системного анализа Левенчука (МФТИ), бесплатные курсы на openedu от УрФУ "Практики системной инженерии", "Информационные сервисы в управлении инженерной деятельностью". Если говорить про API на моём уровне, то это надо понимать программирование достаточно хорошо + знать как создавать API, знать SQL, знать, что происходит в коде и так далее. Лучше всего начать погружаться в это с бизнес-требований и ограничений, постепенно изучая системную аналитику и основы программирования и SQL, чтобы иметь возможность впоследствии писать функциональные требования. Так как системная аналитика на 25-40% состоит из бизнес-аналитики.
@@systemsengineering в курсе по Практике системной инженерии доступна только первая неделя, думаю с остальными аналогичная ситуация. На курсере я ничего не нашёл, по тому что вы скинули. Про Вигерса довольно противоречивое мнение, некоторые советуют читать "Современные методы описания функциональных требований к системам" Коберна. Был бы вам очень признателен хотя бы за один курс по системному анализу)
@@xenx7312 Читать стоит и Коберна и Вигерса и BABOK. Книга К. Вигерса помогает понять окружение, которое формируется вокруг требований. Книга А. Коберна помогает понять как именно их можно писать, а BABOK даёт перечень техник для написания, сбора, валидации (и т.д.) требований на высоко-абстрактном уровне (так что его лучше читать последним). Непосредственно на рабочем месте обычно уже есть шаблоны требований, которые можно использовать, обычно их разработкой занимается либо руководитель отдела аналитики, либо тимлид, либо PMO. Монетизация курсов могла измениться, но скорее всего у вас курс даётся постепенно, проверьте профиль вашего участия, когда откроется следующий материал. Курс длится 12 недель, раскрывается постепенно, по 3-9 учебных часов в неделю. На курсере часто используется такой-же подход ограничений. Возможно в связи с внешними обстоятельствами на курсере теперь нет курсов МФТИ. Курс Левенчука можно найти на его сайте, в книге, которую можно купить\скачать. Уверен, что возможно где-то можно найти видеозаписи курса. Насчёт новых курсов сказать сложно, т.к. я уже 1.5 года нахожусь не в стране. А чтобы оценить курс надо его либо пройти, либо видеть как люди обучаются. Курсы можно поискать тут t.me/spbcoachanel и тут t.me/BA_SA_Arch_edu
1. Создаёшь таблицу. 2. Выставляешь курсор на нужную ячейку. 3. Прожимаешь ctrl + shift + i. Либо используешь элемент управления 'Insert table' сверху в панели обработки текста.
@@eugeneqa8154 Скорее всего это вопрос версии конфлюенса или установленных плагинов. У меня у всех работодателей уже настроена эта возможность. Также, при установки нового конфлюенса с нуля в облаке эта возможность имеется. Здесь вам поможет алассиан-администратор или гугл.
Если вы в прошлом разработчик, то смотрите в код и описываете то, что там происходит. Если нет, то хватаете опытного в этом сервисе разработчика, назначаете с ним встречу на час, и разбираете как всё работает метод за методом. Он рассказывает шаги, вы записываете. Повторяете встречи до тех пор, пока не будет полной документации.
Спасибо, мне как тестировщика это полезно, приходится самому описывать api
Спасибо за рассказ!
Было интересно посмотреть, потому что документирую REST API в Confluence (тех.писатель).
На 90% вручную, оставшиеся 10% - спасают придуманные со временем шаблоны. Описание для внешних читателей. Сносно, но много ручной работы и дисциплины уходит. =)
Даем описание параметров (простые таблицы без вложенности) + примеры в cURL/JSON.
На встраивание Swagger в Confluence не договорились с разработкой и безопасниками. Единственный момент "интерактивности" - написал от руки и выложил JSON-коллекции, чтобы целевой аудитории не нужно было копипастить примеры в Postman.
Изначально использую "объемную" структуру с кучей перекрестных ссылок. Подумывал сделать one-page API reference (тем же page include), потому что вроде как разрабам это удобнее просматривать через CTRL+F. Но вот послушал про то, что "конф не откроет" большое описание - прям сомнения появились, надо ли.
Если аналитик/техпис сразу пишет yaml под разработку, то можно вставлять фрейм и не париться с таблицей. Если безопасники закрыли этот вариант, то стоит спросить их про возможность развернуть шаблон апи в отдельном сервисе на тестовой среде. Без возможности прокидывать запросы в боевую бд, только в тестовую среду с шаблонами ответов.
Но тут два вопроса. Первый - про возможность в фрейм вставлять только один метод. Второй - доступ в конфу не так просто дать даже internal сервису. У нас не вышло.
plantUML раз в 10, как минимум, облегчает работу.
Круто шаблон, хочу больше роликов
спасибо
Отлично, спасибо
Олег, здравствуйте!) большое спасибо за лекцию, очень ценная информация)
Подскажите, пожалуйста, как реализовать СА если есть сценарий с ошибкой.
Например есть запрос, мы идём в смежную систему, по какой то причине смежная система отвечает ошибкой, * какой то процесс*, на стороне клиента видим ошибку. Такой вариант надо описывать на другой странице с новой схемой? Или это можно как то засунуть на эту же страницу? Или все собирать на одной странице это плохая практика?
Ещё вопрос, как указывать описание систем логирования, мониторинга и тд?
Если надо описать процесс обработки ошибки, которую выдаёт внешняя система, то можно конечно нарисовать схему.
Другой вопрос, что таких ошибок может быть много и на каждую схему не нарисуешь.
Значит здесь нужно описать общий подход.
Например, "Если внешняя система отвечает с ошибкой, то приложение должно ответить с ошибкой, завернув текст и код ошибки смежной системы в тело ответа".
Как заворачивать подобные ошибки каждая команда решает сама. Тут подходы разнятся и надо уточнять у ваших разработчиков. Главное знать в каком поле вернётся внешняя ошибка и её код (если он есть), а также какой код будет сформирован вашим приложением.
Тогда ошибка будет читаема и причина будет светиться в логах и внешний сервис будет знать о ней.
Порой внешний сервис не должен знать о внутренней кухне (что у вас и где у вас пошло не так).
Пользователь точно не должен про это знать, т.е. на фронте эта ошибка должна преобразовываться в человеческий текст с причиной ошибки.
Где описывать ошибки внешнего сервиса? Они должны быть описаны на стороне того сервиса. Разработчику можно прикрепить ссылку на их документацию.
Он в целом обычно делает алгоритм сразу на группу кодов: "если получил 400, запиши причину из этого поля ответа внешней системы в это поле ответа, код прокинь сюда, скопируй http status code и выплюнь наружу".
Обычно подобное поведение прописывается дефолтно в стандартах разработки API вашего отдела. Их запаришься писать в каждом сервисе, а так один раз договорились и весь флот API работает в рамках одной модели поведения.
Порой надо описать нетривиальное поведение для конкретных ответов внешней системы. Например, при ошибке от внешней системы надо откатить транзакцию, или повторить запрос с таймаутом, либо пожаловаться в мессенджер и так далее. Можно также явно приписать поведение для http status code или кодов бизнес-ошибок. Так, если объект уже создан, то это считать ошибкой уже не надо, наружу можно отдать соответствующий код. Либо, если сценарий длинный, то указать, что эта ошибка не прерывает выполнение запроса и алгоритм идёт дальше.
На уровне документа технического решения в списке нефункциональных требований можно отметить логирование и мониторинг. Если система новая и люди "ни в зуб ногой" что в логировать, то можно явно прописать (но это выглядит больше как работа разработчика). В том числе можно указать требование к наличию трассировочного идентификатора. Мониторинг зачастую надо явно прописывать в НФТ: какие метрики нас интересуют, за какой срок, в какой момент слать алерты, границы памяти приложения, места на диске, нагрузки, нужен ли дашборд и так далее. Это отдельная большая тема.
@@systemsengineering здоровья Вашим рукам! Большое спасибо 🤗 ❤
Спасибо за видео. Как управляете изменениями в API? Где и как фиксируются изменения, которые нужно внести в API?
Изменения формируются сперва в виде требований в meeting notes, далее переходят в jira task (таска может сразу появиться в JIRA от заказчика). В рамках работы аналитика над задачей, обновляется документация и передаётся в разработку.
Документация должна отчасти показывать ход мысли разработки.
Новые поля добавляются и окрашиваются зелёным цветом. Желательно добавить комментарий в описание, почему поле было добавлено. со временем (после обновления, например, когда очередная фича зашла или спустя n недель) зелёная закраска убирается.
Удаляемые поля не уходят из документации, но зачёркиваются и закрашиваются серым, добавляет комментарий кто и почему убрал поле.
Есть альтернативный путь с документацией напрямую в yaml.
@@systemsengineering круто, спасибо. Как раз сейчас с командой решаем, как вести изменения при доработках API. Пока выбираем между:
1) Добавление цветом.
2) Версионирование с помощью scroll plugin. Создание branch страницы и ссылка на неё в Jira или большое ТЗ в confluence.
3) Каждое изменение описывать на отдельной странице, потом переносить в общую документацию.
@@kudriashov Это проблема. В одной из компаний я пользовался в конфлюенс плагином для контроля версий, но он быстро перегружал страницу и начинались лаги и зависания.
Надо для себя решить, как часто будет обновляться документация API. Если обновляться будет часто и много, то лучше использовать git + yaml, без документации в конфлюенсе. Тут важно учесть, что никому постороннему это API читать не нужно будет (git всё-таки должен быть закрыт).
Соединение нескольких страниц - это реальная боль, так как изменения вносить долго, легко запутаться, перегружается иерархия страниц.
Можно спеку API вести отдельным файлом и крепить к доке, раньше для этого использовали таблицы excel.
Но кажется самое простое (и с другой стороны сложное, т.к. нужны навыки) - это вести API в yaml + документацию по начинке, без указания контракта.
Т.е. получил запрос из метода GET /.../.../... (смотри YAML), дальше описываешь обработку этого запроса, в конце указываешь какие данные в какие поля улетают.
Иначе придётся вести таблицу полей запросов как в конфе, так и в YAML.
Другими словами весь контракт в ямле, история в гите, а как это всё работает внутри сервиса - в конфлюенсе. Только не надо дублировать контракт в конфе, иначе получится двойная работа и могут появиться расхождения.
Но придётся учить как создавать YAML.
Ну и есть другие протоколы передачи данных, для которых yaml не подходит.
Хах, пора уже переставать работать, а то я как психолог из южного парка - повторяю одну и ту же фразу. =)
Спасибо! Очень интересный материал) что можете посоветовать посмотреть/изучить джуну, чтобы прокачаться ?
Обычно я рекомендую читать Карла Вигерса "разработка требований к программному обеспечению" и проходить бесплатные курсы на курсере школы системного анализа Левенчука (МФТИ), бесплатные курсы на openedu от УрФУ "Практики системной инженерии", "Информационные сервисы в управлении инженерной деятельностью". Если говорить про API на моём уровне, то это надо понимать программирование достаточно хорошо + знать как создавать API, знать SQL, знать, что происходит в коде и так далее. Лучше всего начать погружаться в это с бизнес-требований и ограничений, постепенно изучая системную аналитику и основы программирования и SQL, чтобы иметь возможность впоследствии писать функциональные требования. Так как системная аналитика на 25-40% состоит из бизнес-аналитики.
@@systemsengineering Большое спасибо!!!
@Daria Pavlova Курсы без проблем должны гуглиться, книги покупаются. Какие именно ссылки требуются?)
@@systemsengineering в курсе по Практике системной инженерии доступна только первая неделя, думаю с остальными аналогичная ситуация. На курсере я ничего не нашёл, по тому что вы скинули. Про Вигерса довольно противоречивое мнение, некоторые советуют читать "Современные методы описания функциональных требований к системам" Коберна. Был бы вам очень признателен хотя бы за один курс по системному анализу)
@@xenx7312 Читать стоит и Коберна и Вигерса и BABOK. Книга К. Вигерса помогает понять окружение, которое формируется вокруг требований. Книга А. Коберна помогает понять как именно их можно писать, а BABOK даёт перечень техник для написания, сбора, валидации (и т.д.) требований на высоко-абстрактном уровне (так что его лучше читать последним). Непосредственно на рабочем месте обычно уже есть шаблоны требований, которые можно использовать, обычно их разработкой занимается либо руководитель отдела аналитики, либо тимлид, либо PMO. Монетизация курсов могла измениться, но скорее всего у вас курс даётся постепенно, проверьте профиль вашего участия, когда откроется следующий материал. Курс длится 12 недель, раскрывается постепенно, по 3-9 учебных часов в неделю. На курсере часто используется такой-же подход ограничений. Возможно в связи с внешними обстоятельствами на курсере теперь нет курсов МФТИ. Курс Левенчука можно найти на его сайте, в книге, которую можно купить\скачать. Уверен, что возможно где-то можно найти видеозаписи курса. Насчёт новых курсов сказать сложно, т.к. я уже 1.5 года нахожусь не в стране. А чтобы оценить курс надо его либо пройти, либо видеть как люди обучаются. Курсы можно поискать тут t.me/spbcoachanel и тут t.me/BA_SA_Arch_edu
Спасибо большое)
Привет! Подскажи пожалуйста как сделать таблицу в таблице в Confluence?
1. Создаёшь таблицу. 2. Выставляешь курсор на нужную ячейку. 3. Прожимаешь ctrl + shift + i. Либо используешь элемент управления 'Insert table' сверху в панели обработки текста.
@@systemsengineering А вот и не получилось
@@eugeneqa8154 Скорее всего это вопрос версии конфлюенса или установленных плагинов. У меня у всех работодателей уже настроена эта возможность. Также, при установки нового конфлюенса с нуля в облаке эта возможность имеется. Здесь вам поможет алассиан-администратор или гугл.
Ох, а как сделать revers engineering если нет такой документации 😅
Если вы в прошлом разработчик, то смотрите в код и описываете то, что там происходит. Если нет, то хватаете опытного в этом сервисе разработчика, назначаете с ним встречу на час, и разбираете как всё работает метод за методом. Он рассказывает шаги, вы записываете. Повторяете встречи до тех пор, пока не будет полной документации.