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

【问题标题】：Does Swagger 2.0 enable impure REST API design?Swagger 2.0 是否支持不纯的 REST API 设计？
【发布时间】：2016-03-25 01:10:05
【问题描述】：

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

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

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

基本上，我认为使用 Swagger 2.0 规范定义的 API 会引导您设计一个不受 HATEOAS 约束的 API，这会违反 REST。

这是正确的还是我遗漏了什么？

【问题讨论】：

为什么这个问题有这么多反对票？这是一个有效且很好的问题。如果您投反对票，请给出理由。
见meta.stackoverflow.com/questions/254570/…
@Tommy 感谢您的解释。我实际上并不熟悉 Progammers SE。从本质上讲，这是一个软件架构问题，因此从技术上讲，Progammers SE 更合适。但是，我看到很多这样的问题在 SO 上很受欢迎，所以看到这么多反对票，我仍然感到惊讶。

标签： api rest http swagger swagger-2.0

【解决方案1】：

我完全同意。 Swagger 不太适合定义真正符合 REST 的 API。问题是人们以许多不同的方式定义 REST。 Richardson 成熟度模型有助于描述这些不同的定义。

Level 0 REST API 通过一个 URI 和一个 HTTP 方法传递所有请求。此级别包括使用 HTTP 的任何 API，无论其有多么有限。在实践中，人们很少再称它为 REST，但它确实发生了（可能出于营销原因）。

1 级 REST API 使用许多 URI，但仍然只使用一种 HTTP 方法（通常是 POST）。同样，在实践中，这已很少称为 REST，但曾有一段时间它很常见。

Level 2 REST API 是引入资源和统一接口概念的地方。这些 API 具有表示资源的 URI，并使用 HTTP 方法对这些资源执行 CRUD 操作。在实践中，人们开始将其称为 RESTful 以将其与 Level 1 区分开来。我感谢 Ruby on Rails 普及了对 REST 的这种解释，但我不能支持这一点。在任何情况下，当 Swagger 声称用于描述 RESTful API 时，Level 2 就是他们所指的定义。

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

我会说你对 REST 的理解比 Swagger 使用的更“成熟”，因此，你只会在尝试使用它时感到沮丧（我是根据经验说话）。我个人对定义超媒体 API 的选择是JSON Hyper-Schema。它无法与 Swagger 拥有的所有出色工具相媲美，但它允许我编写级别 3 的 API。对于任何流行的 API 定义语言，这比我能说的要多。

【讨论】：

感谢您的回复！我终于通过Fowler blog post 检查了理查森成熟度模型，不得不说我更喜欢你的描述。 Fowler 似乎将 RMM 描述为一个过程，但我认为使用它来对“REST”服务进行分类是正确的。
我还想分享一下，我认为 Github 的 API是真正的 REST（超媒体 API）并且是一个很好的 API 来学习和建模。查看他们关于PRs API 的文档。
很高兴您发现我的回答很有用。我听说过关于 Github 的 API 的好消息，但我自己没有评估过。我去看看。