Swagger 2.0是否支持不纯的REST API设计？

Question

当前的Swagger规范声称Swagger用于描述和记录RESTful API.我认为情况并非如此,我认为Swagger对于简单描述HTTP API 非常有用,原因如下:

1. Swagger规范具有类似的元素Path,Definition但它们没有明确映射到REST数据元素,如资源,表示和媒体类型.我的想法是,为了有效地描述REST API,您应该被要求在API的上下文中定义显式REST数据元素.
2. 超链接不是Swagger规范中的第一类对象,因此超链接及其关键描述属性链接关系很容易被忽略.事实上,根本没有提到超链接.
3. HTTP路径位于前端和中心,这似乎明显违反了Fielding在其着名博客文章中提出的观点:

REST API不能定义固定资源名称或层次结构(客户端和服务器的明显耦合)

从本质上讲,我认为使用Swagger 2.0规范定义的API会导致您设计一个不受HATEOAS约束的API,这会违反REST.

这是正确的还是我错过了什么？

Answer 1

我绝对同意.Swagger不适合定义真正的REST兼容API.问题是人们以很多不同的方式定义REST.理查森成熟度模型有助于描述这些不同的定义.

0级 REST API通过一个URI和一个HTTP方法管理所有请求.此级别包括使用HTTP的任何API,无论多么有限.在实践中,人们很少再使用这个REST,但它确实发生了(可能出于营销原因).

1级 REST API使用许多URI,但仍然只使用一种HTTP方法(通常是POST).再一次,在实践中,这个很少被称为REST,但有一段时间它很常见.

2级 REST API是引入资源和统一接口概念的地方.这些API具有表示资源的URI,并使用HTTP方法对这些资源执行CRUD操作.在实践中,人们开始将其称为RESTful以将其与Level 1区分开来.我相信Ruby on Rails可以推广REST的这种解释,但我无法支持它.无论如何,当Swagger声称用于描述RESTful API时,Level 2就是他们所指的定义.

3级 REST API完全符合REST架构风格.特别是,它们的特点是使用HATEOAS.您在问题中提出的所有问题都不会在此级别之前考虑在内.实际上,有些人已经开始调用这些超媒体API,以便将它们与现在根深蒂固的RESTful定义区分开来,因为它引用了Level 2定义.

我会说你对REST的理解比Swagger使用的更加"成熟",因此,你只会在尝试使用它时感到沮丧(我从经验中说).我个人选择定义超媒体API是JSON Hyper-Schema.它无法与Swagger所拥有的所有优秀工具相匹敌,但它允许我在3级编写API.对于任何流行的API定义语言来说,这都是我所能说的.