Основное различие между Swagger и HATEOAS IMO, которое не отражено в принятом ответе, заключается в том, что Swagger необходим только для API-интерфейсов RPC.Однако такие API практически не имеют ничего общего с REST.
Существует еще одно распространенное заблуждение, что все, что обменивается через HTTP, автоматически является RESTful (~ в соответствии с архитектурным стилем REST), а это не так.REST просто определяет набор ограничений, которые не являются вариантами или опциями, но являются обязательными.От начала до конца.Нет ничего плохого в том, что он не является RESTful, но неправильно называть такую архитектуру REST.
Swagger описывает операции, которые могут выполняться на конечной точке, и полезную нагрузку (включая заголовки и ожидаемые форматы представления), которыеНеобходимо отправить в службу, а также описать, что клиент может ожидать в качестве ответа.Это позволяет использовать Swagger как документацию, а также как основу для тестирования API.Из-за тесной связи Swagger с API, он ведет себя во многом как типичное описание службы RPC, то есть похоже на файлы WSDL в SOAP или классы заглушек или скелетов в RMI или CORBA.Если либо изменяется конечная точка, либо что-то меняется в полезной нагрузке, клиенты, внедряемые в соответствии с документацией Swagger, вероятно, со временем будут ломаться, просто повторяя те же проблемы, что и типичные реализации RPC.для открытия и дальнейшего развития.REST - это не протокол, а архитектурный стиль, с которого начинается поток взаимодействия между клиентом и сервером в распределенной системе.В основном он взял концепции, которые сделали Интернет настолько успешным, и перевел его на прикладной уровень.Таким образом, те же понятия, которые применимы к просматриваемой сети, также применимы к REST.Поэтому неудивительно, что HATEOAS (использование и поддержка ссылок, отношений ссылок и имен ссылок) ведет себя подобно Интернету.
При проектировании архитектуры REST полезно подумать о конечном автомате, в которомСервер предоставляет всю информацию, необходимую клиенту для принятия дальнейших действий.В 2016 году Асбьёрн Ульсберг провел отличную беседу, в которой он объясняет возможности и то, как конечный автомат может быть реализован с помощью HATEOAS .Помимо общих или стандартизированных медиа-типов и имен отношений, внеполосные знания не требуются для дальнейшего взаимодействия со службой.В случае с тостером, который Асбьерн привел в своем выступлении, тостер может иметь состояния off, on, heating и idle, где включение тостера приведет к переходу состояния из off вon с последующим переходом на heating до достижения определенной температуры, когда состояние переходит на idle и переключается между idle и heating до выключения тостера.
ХАТОАСпредоставит клиенту информацию о текущем состоянии и включит ссылки, которые клиент может вызвать для перехода в следующее состояние, то есть снова выключить тостер.Здесь важно подчеркнуть, что сервер предоставляется клиентом для каждого действия, которое клиент может выполнить дальше.Клиентскому разработчику не нужно обращаться к какой-либо проприетарной документации API, чтобы клиент мог взаимодействовать со службой REST.Кроме того, URI не должны быть осмысленными или предназначенными для передачи семантически выразительной структуры, поскольку клиенты будут определять, имеет ли смысл использовать этот URI через имя отношения ссылки.Такие имена отношений задаются либо IANA , с помощью общего подхода, такого как Dublin Core или schema.org , либо абсолютными URI, действующими как атрибуты расширения, который может указывать на удобочитаемое описание, которое затем может быть передано пользователю с помощью всплывающих подсказок мыши или чего-то подобного.
Надеюсь, вы сами видите, что Swagger необходим только для описания RPC Web-API, а не приложений, которые соответствуют архитектуре REST.Сообщения, которыми обмениваются через API REST, должны включать всю информацию, необходимую клиенту для принятия осознанного выбора при следующем переходе состояния.Таким образом, полезно создавать такие потоки сообщений и взаимодействия, как конечный автомат.