OpenAPI для асинхрона - а, пожалуйста

Я думаю все знают, как описать API для REST взаимодействия. OpenAPI давно уже стал стандартом.

Перечислю его основные плюсы:
1) широкое распространение
2) автоматическая генерация документации
3) онлайн редактор Swagger UI
4) генерация серверного и клиентского кода по схеме
5) стандарт покрывает не только собственно содержимое body сообщения, но и описывает всю схему взаимодействия: параметры URL, заголовки включая куки, коды ошибок. Даже адреса серверов, хотя как по мне - это спорный момент.

Но асинхронное взаимодействие, ака Event-Driven Architecture: Kafka, MQ.. - имеют свои особенности. Как минимум это:
1) нет понятия запрос-ответ, вместо этого обмен идет сообщениями
2) другой набор протоколов (хотя http есть и там, и там)
3) другая терминология - есть каналы (топик или очередь), у канала есть свои характеристики
4) в любом взаимодействии нужно описать 3 участников: producer, канал, consumer.

Поэтому появился AsyncAPI. Он достаточно сильно похож на OpenAPI:
1) тот же YAML,
2) похожи (с точностью до сказанного выше) основные блоки, из которых строится API - Info, Servers, Tags, Schemas...
Видно чем вдохновлялись авторы) Как сказано на официальном сайте: "Part of this content has been taken from the great work done by the folks at the OpenAPI Initiative."
И это хорошо.

Стандарт молодой, но уже стал стандартом ))) да, тавтология) Имеет все те же преимущества, что и OpenAPI - см. начало поста.
Вот неплохая статья с примером https://bigdataschool.ru/blog/asyncapi-specification-for-kafka-practical-example.html

Поэтому настоятельно рекомендую для использования.

#api #openapi #asyncapi

Как быстрее погрузиться в код?

Речь про существующий микросервис и нового разработчика.
Я уже писал, что JavaDoc (KDoc) не является обязательным для каждого метода\поля или класса (как минимум для бизнес-приложения, общие библиотеки - особый кейс), т.к. документацию никто не читает.
А что же тогда будет документацией? Например, тесты. Их конечно тоже новичок не будет читать на 100%, но во-первых их и так нужно писать, а во-вторых - при рефакторинге падающий тест покажет, что забыли поправить, а в целом любой существующий тест изменяемого класса покажет, как он работает.

А недавно я нашел еще один полезный способ задокументировать микросервис так, чтобы этой "документацией" пользовались.
Начну немного издалека. Есть такая ИТ консалтинговая компания как Thoughtworks. Ну есть и есть, где мы и где консалтинг. Но там работает такой небезызвестный человек, как Мартин Фаулер. Главный научным руководителем https://www.thoughtworks.com/profiles/leaders/martin-fowler
А это внушает некий уровень доверия.
Так вот, компания ведет реестр технологий а-ля техрадар.
И в текущей его версии есть такая штука https://www.thoughtworks.com/en-de/radar/techniques/api-request-collection-as-api-product-artifact
как коллекция API запросов как артефакт продукта.
На самом деле мысль лежит на поверхности, я уже достаточно давно практикую прихранивание запросов в формате IDEA api collection вместе с исходниками в тех проектах, над которыми приходилось работать. Да, над форматом стоит подумать отдельно, возможно Insomnia будет по-универсальнее, зависит от команды и организации. Но сама идея мне очень нравится. Такой документацией точно будут пользоваться.

P.S. Кто ее должен делать - разработчики или тестировщики и нужно ли шарить коллекцию между ними - тоже вопрос для обсуждения. В идеале - думаю, что да.

P.P.S. Да, когда я говорю про артефакт продукта - это значит мало ее сделать, ее нужно поддерживать в актуальном состоянии.

#api #onbording #documentation