Поддерживает ли Swagger 2.0 нечистый дизайн REST API?

Текущая спецификация Swagger утверждает, что Swagger используется для описания и документирования RESTful API. Я думаю, что это не так, скорее я думаю, что Swagger полезен для простого описания HTTP API по нескольким причинам:

  1. В спецификации Swagger есть такие элементы, как Path и Definition, но они явно не соответствуют элементы данных REST, такие как ресурсы, представления и типы мультимедиа. Я считаю, что для эффективного описания REST API вам необходимо определить явные элементы данных REST в контексте вашего API.
  2. Гиперссылки не являются объектами первого класса в спецификации Swagger, и поэтому гиперссылки и их критический описательный атрибут, отношение ссылки, могут быть легко опущены. На самом деле гиперссылки вообще не упоминаются.
  3. Пути HTTP находятся впереди и в центре, что кажется явным нарушением точки зрения Филдинга, сделанной в его знаменитом запись в блоге:

REST API не должен определять фиксированные имена ресурсов или иерархии (очевидная связь клиента и сервера).

По сути, я думаю, что API, определенные с использованием спецификации Swagger 2.0, приводят вас к разработке API, который не ограничен HATEOAS, что нарушит REST.

Это правильно или я что-то упускаю?


http api rest swagger swagger-2.0
person mikehwang    schedule 25.03.2016    source источник
comment
Почему так много голосов против этого вопроса? Это правильный и хорошо поставленный вопрос. Если вы голосуете против, укажите причину.   -  person Jason Desrosiers    schedule 25.03.2016
comment
см. метаданные .stackoverflow.com/questions/254570/   -  person Tommy    schedule 13.04.2016
comment
@ Томми Спасибо за объяснение. На самом деле я не был знаком с Progammers SE. По сути, это вопрос архитектуры программного обеспечения, поэтому технически Progammers SE более подходит. Тем не менее, я видел много подобных вопросов, которые были хорошо приняты на SO, поэтому я все еще удивлен, увидев так много отрицательных голосов.   -  person Jason Desrosiers    schedule 13.04.2016

Ответы (1)


arrow_upward
6
arrow_downward

Я абсолютно согласен. Swagger плохо подходит для определения действительно совместимых с REST API. Проблема в том, что люди определяют REST по-разному. Модель зрелости Ричардсона помогает описать эти различные определения.

Уровень 0 API REST передают все запросы через один URI и один метод HTTP. Этот уровень включает в себя любой API, который использует HTTP, независимо от того, насколько он ограничен. На практике люди редко называют это REST, но это действительно происходит (вероятно, из маркетинговых соображений).

REST API уровня 1 используют множество URI, но по-прежнему используют только один метод HTTP (обычно POST). Опять же, на практике это редко называется REST, но было время, когда это было обычным явлением.

Уровень 2 REST API — это то место, где представлены концепции ресурсов и единого интерфейса. Эти API имеют URI, которые представляют ресурсы и используют методы HTTP для выполнения операций CRUD с этими ресурсами. На практике люди стали называть это RESTful, чтобы отличить его от уровня 1. Я благодарен Ruby on Rails за популяризацию этой интерпретации REST, но не могу это подтвердить. В любом случае, когда Swagger утверждает, что описывает RESTful API, они имеют в виду определение уровня 2.

REST API уровня 3 полностью соответствуют архитектурному стилю REST. В частности, для них характерно использование HATEOAS. Все проблемы, которые вы изложили в своем вопросе, не принимаются во внимание до этого уровня. На практике некоторые люди начали называть эти API-интерфейсы Hypermedia, чтобы отличить их от укоренившегося определения RESTful как относящегося к определению уровня 2.

Я бы сказал, что ваше понимание REST более «зрелое», чем то, которое использует Swagger, и поэтому вы будете только разочарованы, пытаясь его использовать (я говорю по опыту). Лично я выбрал для определения Hypermedia API JSON Hyper-Schema. Он не может сравниться со всеми замечательными инструментами, которые есть у Swagger, но он позволяет мне писать API на уровне 3. Это больше, чем я могу сказать о любом из популярных языков определения API.

person Jason Desrosiers    schedule 25.03.2016
comment
Спасибо за ответ! Наконец-то я смог изучить модель зрелости Ричардсона в сообщении в блоге Фаулера и должен сказать, что Ваше описание мне нравится намного больше. Фаулер, кажется, описывает RMM как процесс, но я думаю, что правильно использовать его для классификации REST-сервисов. - person mikehwang; 12.04.2016
comment
Я также хочу поделиться тем, что я думаю, что API Github является действительно REST (Hypermedia API) и хорошим API для изучения и моделирования. Ознакомьтесь с их документацией по API для PR. - person mikehwang; 12.04.2016
comment
Я рад, что вы нашли мой ответ полезным. Я слышал хорошие отзывы об API Github, но сам не пробовал. Я проверю это. - person Jason Desrosiers; 12.04.2016