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

Question

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

1. Swagger 规范包含 Path 和 Definition 等元素，但它们没有明确映射到 REST data elements例如资源、表示和媒体类型。我的想法是，要有效地描述 REST API，您应该需要在 API 的上下文中定义明确的 REST 数据元素。
2. 超链接不是 Swagger 规范中的一流对象，因此很容易将超链接及其关键描述性属性(链接关系)排除在外。事实上，根本没有提到超链接。
3. HTTP 路径位于前端和中心，这似乎明显违反了菲尔丁在其著名的 blog post 中提出的观点。 :

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server)

从本质上讲，我认为使用 Swagger 2.0 规范定义的 API 会引导您设计一个不受 HATEOAS 限制的 API，HATEOAS 会违反 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 是引入资源和统一接口(interface)概念的地方。这些 API 具有表示资源的 URI，并使用 HTTP 方法对这些资源执行 CRUD 操作。在实践中，人们开始将其称为 RESTful 以将其与 Level 1 区分开来。我认为 Ruby on Rails 普及了对 REST 的这种解释，但我不能支持这一点。无论如何，当 Swagger 声称用于描述 RESTful API 时，他们指的是第 2 级定义。

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

我想说您对 REST 的理解比 Swagger 使用的更“成熟”，因此，您在尝试使用它时只会感到沮丧(我是根据经验说的)。我个人定义超媒体 API 的选择是 JSON Hyper-Schema .它无法与 Swagger 拥有的所有出色工具相提并论，但它允许我在第 3 级编写 API。对于任何流行的 API 定义语言，我都无法说出这一点。