Простой ликбез почему Swagger ≠ OpenAPI

У нас в команде всё, что касается документации REST API, по привычке называют «сваггер» (догадайтесь, кто виноват? 🙈).
А между тем Swagger один из инструментов, а не сама документация. Поэтому сейчас переучиваемся.

И так как виновата я, то взяла ответственность на себя и подготовила памятку для коллег с разъяснениями. Делюсь и с вами.

📌 Спецификация OpenAPI (OAS) 📌
конкретный YAML/JSON-файл или набор таких файлов, описывающий ваш API. Это источник правды для документации и автогенерации кода.
Я люблю править спеку в VS Code с набором плагинов (если нужен список дайте знать). Но можно в любом YAML-редакторе. А если JSON/YAML пока пугает попробуйте Stoplight Studio.

📌 OpenAPI-документация 📌
красивое, человекочитаемое отображение спеки, которое может быть в Swagger, но не обязательно. Мне нравится ещё Redoc.

📌 Swagger UI 📌
инструмент для отображения в браузере или в Visual Studio. Легко читать, можно даже делать запросы, но менять к нем спеку нельзя.


Путь работы: Придумываем новые эндпоинты → Описываем их в спецификации OpenAPI → Пушим изменения в репозиторий → Ревью →
CI/CD подхватывает обновления, валидирует спеку → Собирает и разворачивает документацию в Swagger UI → С ней начинают работать бэки и фронты

Если вы всё ещё зовёте всё это “сваггером” — просто пересылайте этот пост коллегам

#Swagger #OpenAPI #СистемныйАнализ

Видимо я мастер путать людей, и мне удалось не только запутать своих коллег, но и некоторых из вас.

Ответ JSON, YAML, XSD был ошибочно поставлен, как правильный. Хотя таким не является.
Конечно же XSD никак не связан с OpenAPI

Была на лекции по архитектуре… городской архитектуре.

Слушала и понимала: у них всё как у нас.
Задача: реставрировать старое легаси, сохранив его изюминку. Но переосмыслить ещё и его применение! А сохранить нужно, потому что это дорогое сердцу, уникальное наследие. Если вы сейчас пустили слезу я вас понимаю.

Всё было хорошо продумано, спроектировано и с какого то этапа даже был бюджет. Что шло не так?
Упс, но не ожидали, что за много лет развития территории вокруг здания и особенности почв под ним будут собираться подземные воды. А именно в подвале планировали всю развязку коммуникаций, в том числе электрики.

Не было работяг, которые умеют работать по старым технологиям. Пришлось нанимать отдельную женщину-надсмотрщицу, которая следила, чтобы учились и соблюдали. Про нее до сих пор сняться кошмары рабочим.

Архитекторы очень хотели сделать у сада реку.. и снова не вышло. Оказалось, подземных вод мало, а они рассчитывать такое не умели.

Прибежали и ландшафтные дизайнеры, и оказалось, что архитекторы запланировали высадить на территории инвазивные виды. Потому что красиво. И символично. Что то это напоминает?

Да и потребности у современных помещений другие: по энергоэффективности, освещению и прочему. И вместе со старым фундаментом легаси оно плохо уживается.

Чтобы сделать реставрацию, на самом деле пришлось здание практически очистить от всего, что было. Остался в прямом смысле скелет, который укрепили разными способами, которые пришлось изобретать на колене растягивая бюджет и срок.

Зато сегодня в Самаре есть потрясающий филиал Третьяковки на месте старого советского здания в стиле Модернизм. И это точно того стоило.

Стоит ли сегодня то же самое делать с программами? Наверное, нет. Но кто знает, может лет через 50 тоже будут музеи "сохранения культурного наследия", объектами которого будут ИТ программы.

#легаси #архитектура #модернизм #выходнойконтент

Промт-инжиниринг: ерунда или новая грамотность?

Несмотря на то, что ИИ уже прочно часть моей работы и жизни, я все истории про промт-инженеров и сложности составления промтов воспринимала больше как хайп и юмор.

Почему?

1️⃣ Для меня постановка задачи к команде разработки и к ИИ про одно и то же. В каждом случае вводишь в контекст, даёшь все вводные, объясняешь, что стоит использовать и к чему нужно прийти на выходе. Более того, это основа любого общения, где задача быть понятым. То есть в отношениях с родными, друзьями и всем окружающим миром.

Даже особенности работы с ИИ всё же есть, связанные с галлюцинациями, напоминают обычные правила коммуникации. Например:
— «Если не знаешь, не придумывай, а скажи, что не знаешь».
— «Если вводных недостаточно, задай вопросы».
— «Не отходи от изначальной темы».
— «Опирайся на проверенные источники».

2️⃣ Копаясь в базах данных промтов, я скорее видела, что просто не всем доступно в обычной жизни искусство разъясняться. А у аналитиков это уже профессиональное: если не хочешь результат “ХЗ”, то делай нормально ТЗ.

3️⃣ Часто к ИИ мы обращаемся не за уникальной сложной работой, а за рутиной. И там даже модели двухгодичной давности, бесплатные, справляются неплохо, с промтами, которые «ну такое себе». Отлично это демонстрирует доклад Алишера Умарова А последние модели уже и вовсе предугадывают контекст и требуют меньше данных на входе.

Между тем недавно я стала участником конкурса от Systems Education #продолжи_мысль_SE, и там многие писали именно про промты. Вначале я решила, что это не стоит моего внимания, но одновременно с конкурсом произошёл забавный случай:

Идёт обсуждение внедрения ИИ в одну из систем. И представители команды внедрения ИИ говорят: «Вам нужно будет нанять промт-инженера!». Мой мир переворачивается: почему серьёзные компании тратят деньги на «ерунду» в виде промт-инженеров?

Пришлось возвращаться к постам и осмыслять. Больше всего меня зацепил пост «Ментальная карта промтов для аналитика», как и сам канал Елены посвященный во многом промтам.

Сначала находила подтверждения скепсису, но чем глубже читала, тем яснее видела системность карты. Через некоторое время я поняла, почему

«ментальная карта промтов это способ мыслить, делегировать и усиливаться как аналитик».

«Как аналитик» здесь очень важно. Промты это возможность с помощью чужого опыта получить классное решение на рутинную и не очень задачу.

Карта получилась очень объёмная, но не перегруженная, как один из самых известных источников промтов.

Практикующему системному аналитику с помощью карты можно ускорить время не только за счёт использования ИИ, но и за счёт подготовки задач для ИИ. По факту это всесторонний чек-лист аналитика.

Для начинающих специалистов и менторов интерес могут представлять и сами промты. Некоторые из них можно использовать для обучения джунов: чтобы они сами пробовали по ним делать задачу и понимали, на что опираться.

А ещё такая карта подойдёт тем, кто всё же не может совладать с искусством промт-инжиниринга. По карте легко изучать, осмыслять и пробовать!

Нашлось кое-что полезное и для меня в разделе про сам промт-инжиниринг. А именно несколько интересных промтов, как прокачать ответы и уменьшить галлюцинации.

Из минусов: большинство примеров промтов всё же на базовый и стандартный уровень. У моего супруга такой уровень SQL на работе требуется, что предложенные промты ему точно не помогут. Но это уже про особенности конкретной работы аналитиком, чем про карту.
Ещё момент: карту просто так не получишь. Я такое ограничение не одобряю, хотя оно и стимулирует не просто сохранить пост, а действительно осмысленно получить карту и потом её использовать.

Изменилось ли моё отношение к промт-инжинирингу после поста с картой? И да, и нет, но точно стало теплее.

А ещё пост навёл меня на мысль: может оказаться, что обучение промт-инжинирингу поможет не только в работе с ИИ? Может, всё больше людей сможет лучше изъясняться друг с другом и в обычной жизни? Или наоборот, мы всё заменим ИИ, например, как заменили поздравления и нецензурные письма коллегам.)

Напоминаю, что уже завтра стартует в Самаре конференция аналитиков Поволжья SAMBA_CONF

Завтра онлайн день, а в воскресенье будет оффлайн!

Жду с нетерпением, так давно такого не было в Самаре)

Я для участников подготовила воркшоп по EventStorming, сначала хотела с другой темой выступить, но так соскучилась сама по ES в живую, что решила все же пойти по уже знакомому пути.

Промокод на скидку 20% от меня

@ANALYTICAGAIN

Плагины для Visual Studio Code для описания OpenAPI

Вообще описание OpenAPI-спецификации простая рутинная работа, которую можно поручать новичкам и где-то ИИ. Но я люблю иногда такие задачки оставлять на себе: когда постоянно работаешь с хаосом, рутина успокаивает и дает положительное подкрепление выполненной работы, среди долгоиграющих задач.

Но облегчать себе жизнь всё же нужно. И вот мой набор расширений для VS Code которые помогают в этом:

Редактор, проверка и валидация

🔧 YAML от RedHat🔧 Кажется, он всегда предустановлен. Но версия 1.18 косячная, лучше откатиться до 1.17. Это и редактор, и автодополнение, и переходы по $ref (в том числе между файлами). В целом может быть достаточно, если нет возможности ставить сторонние расширения.

🔧 OpenAPI (Swagger) Editor🔧 Есть шаблоны для новых документов, удобный редактор, очень нравится возможность ходить по дереву описанного документа.

🔧 Stoplight Spectral🔧 Линтер с готовыми правилами для OpenAPI. Фишка, что можно добавлять свои правила. Но пока я ленивая какашка, и не добавила в правила договорённостей в команде. Поэтому он меня часто раздражает, из-за своих правил. Но мы с коллегой договорились довести его до ума и встроить в процесс CI/CD (расскажу о результатах отдельно).

Предпросмотр

👀 Swagger Viewer 👀 Классика. Показывает, что же вы там понаписали и собирается ли это вообще. В последних версиях появился поиск — очень удобно.

Тестирование

🧪 Thunder Client 🧪 Простенький аналог Postman. Для большинства REST-задач мне хватает, плюс удобно, что всё прямо внутри VS Code.

Ну конечно еще ряд расширений для Git. Но там стандартный набор.

Вот такой нехитрый набор, который делает простую работу ещё проще. Рекомендую.

Расширения с ИИ для работы с OpenAPI-спецификацией ещё не искала, поэтому если знаете хорошие, делитесь!

👀Не люблю работать с сеньорами

Самые сложные случаи работы в команде, где возникало больше всего проблем, были связаны с работой с сеньорами. Мне везло работать с классными, опытными специалистами, с которыми мы реализовывали различные фичи. Но что отличало большинство из них? Огромное количество опыта, знакомство с типовыми кейсами, уверенность в том, как должно быть.

Почему же возникали сложности?

1️⃣ Если сеньор видел, что где-то можно сделать лучше, он это делал, не предупредив и не выяснив, почему было выбрано другое решение.
К чему это приводило: переставало работать то, что уже давно работало, или происходили большие расхождения с требованиями.

2️⃣Свои гениальные решения сеньоры редко кому-то объясняют.
К чему это приводит: сборная солянка решений для однотипных задач. Команда не понимает, почему это решение лучше, обмен знаниями не происходит, рост затрудняется.

3️⃣Сеньоры часто пренебрегают чужим опытом. Они уже многое видели, и если чего-то не знают, значит, это ерунда.
К чему это приводит: к часовым созвонам и подготовке доказательств, почему твое решение имеет право на жизнь. Если это сочетать с пунктом 2, такие обсуждения превращаются в настоящие детективные расследования.

4️⃣Склонность к микроменеджменту.
К чему это приводило: меня всегда бесили те, кто из отпуска писали, что точка в ответе на ошибку важна. Лучше бы вы так делились своим опытом.

5️⃣Сеньоры не дают раскрыться другим специалистам, особенно джунам. Это такая айти-дедовщина.
К чему это приводит: часть новичков уходит, а другие становятся равнодушными. Ошибки начинают копиться, потому что всегда есть сеньор, который всё равно "достанет" тебя, как бы хорошо ты не сделал.

6️⃣Некоторые сеньоры, повидавшие "Г…", становятся равнодушными и токсичными. Часто они работают спустя рукава, а прикрываются нападками на других.
Помните мой пост про ретроспективу? Так вот, главный токсик был сеньором.

🛠
Конечно, не все сеньоры такие. И здесь у меня есть совет только самой себе: когда дорасту до нужного уровня, не забывать, что сила в командной работе. Никогда не забывать о важности делиться своими знаниями и объяснять свои решения. Оставаться гибкой к новым технологиям, мнениям и людям. Открытые диалоги — сила вне зависимости от опыта. И да, учиться нужно будет всегда.

А как у вас обстоят дела в работе с сеньорами?

#СистемныйАнализ #КарьеравИТ #сеньор