OpenAPI

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

Получилось душевно, с интересными вопросами, в том числе из разряда "А это вообще реально применить у нас и договориться с разработчиками об использовании такого подхода?" Что, кстати, является весьма важным поинтом, потому что без их участия это все бессмысленно - особенно если они будут игнорировать описанные контракты и делать отсебятину, без оповещения аналитика об изменениях. Но на этот вопрос у меня не было ответа)

Планирую провести на эту тему воркшоп в следующем месяце. Когда подготовлю кейсы и буду готов - сделаю дополнительный анонс.

Я уже рассказывал про Swagger\OpenAPI вот в этом посте. Сейчас хочу более подробно раскрыть те блоки, из которых состоит контракт, описанный в спецификации OpenAPI, и что в них нужно указывать.

Но перед этим важно упомянуть, что между версиями спецификации 2.0 и 3.0 есть достаточно весомые отличия, особенно в наименовании различных полей (хоть и общая суть идентична), которую тоже стоит учитывать. Я буду рассказывать сразу про версию 3.0, т.к. она наиболее актуальная на данный момент.

И еще момент, советую для описания использовать editor.swagger.io, т.к. это наиболее удобный и широкий инструмент, который кроме всех прочих функций будет отображать вам визуальное представление описанных контрактов и валидировать его. Можно прям открыть его, при первом открытии у вас откроется пет-проект, который можно поизучать.

Список корневых элементов контракта:

➖openapi: 3.0.0
Это обязательный атрибут спецификации, без которого она не будет считаться валидной. Тут указывается именно версия спецификации, не контракта вашего сервиса.

➖info:
Этот блок также является обязательным. В нем мы задаем наименование нашего сервиса, его версию, описание и различную контактную информацию (например, какая команда им владеет, чтобы можно было понять, к кому обращаться с вопросами).

➖externalDocs:
В этом блоке можем дать различные ссылки на документацию сервиса, например на описание его логики работы в конфлюенсе.

➖servers:
Тут мы можем указать массив ссылок на сервера, на которых крутится описываемый сервис. Например его хосты с прода и теста.

➖tags:
В этом блоке мы можем задать массив тэгов, которые потом сможем присваивать нашим endpoint'ам. Тэги — это просто визуальная группировка наших методов по бизнес-юниту, по какому-то техническому признаку или вашему хотению. Например, если ваш микросервис работает с заявкой на кредит, то вы можете выделить тэги LoanApplication, ApplicationOffers, ApplicationStatus, ApplicationScore и т.д. И каждому методу, который вы будете далее описывать присвоить один или несколько из этих тэгов.

➖components:
Это очень важный блок, в котором вы описываете модель данных, с которой работают ваши методы. Это необходимо для того, чтобы в рамках контракта один раз задать какие-либо сущности и потом просто ссылаться на них, вместо того, чтобы объявлять в рамках каждого метода одни и те же объекты. Например, у вас есть метод, который возвращает список заявок и метод, который возвращает одну конкретную. Модель данных у них будет почти одинаковая, кроме того, что в первом случае будет массив заявок. И вот вместо того, чтобы в двух местах описывать все сотни атрибутов, которыми обладает заявка - мы делаем это один раз и потом ссылаемся на эти сущности.

➖paths:
Самый важный и тоже обязательный блок. Именно в рамках него мы описываем все имеющиеся endpoint'ы и все их методы. Как это сделать - расскажу в следующем посте.

Итого: для проектирования контракта нужно минимально иметь блок openapi, info и paths. Остальные опциональные (но очень желательно их тоже описывать).