Swagger 和 RESTful spring hatoas 资源答案

【问题标题】：Swagger and RESTful spring hateoas resourcesSwagger 和 RESTful spring hatoas 资源
【发布时间】：2015-01-21 13:26:18
【问题描述】：

在我的 RESTful API 中，所有资源都扩展了 Spring 的 ResourceSupport 基础，以便在设计上确保 hatoas 主体。例如：

public class PoolResource extends ResourceSupport {
    private String name;
    ...
}

我也在使用 Swagger，我想知道：是否可以以某种方式配置 swagger-ui，以忽略来自 ResourceSupport 的属性？

(Swagger-ui 提供了一个漂亮而简单的 API 前端。作为使用 Swagger 的主要好处之一，对于那些甚至不熟悉 REST 的人来说，该 API 易于理解和使用该 API API ...只要“链接”和“rels”出现在图片中。）

【问题讨论】：

如果你不想要超媒体，你为什么首先使用 Spring HATEOAS？如果你想要超媒体，为什么要使用 Swagger（它积极颠覆超媒体）？
我想要超媒体。在研究了 RESTful 原理之后，我明白了拥有超媒体的好处，所以我真的很想设计一个level 3 API。这就是使用 Spring HATEOAS 的原因。但大多数 API 用户仍然不了解超媒体，根本不明白为什么它很好。对他们来说，swagger 提供了一个非常酷的完整 API 视图。将它呈现给任何人都非常好，即使从我的祖母到高级开发人员也很容易理解。 Swagger“颠覆超媒体”是什么意思？
大多数答案建议我不要使用 swagger，glory of REST 将解决我的大部分问题。好吧，让我们想象一下，我扔掉了招摇。这让我想到了这样的问题： - 我有资源Pool。如果我有一个新安装的系统，没有任何现有的池实例，所以我无法获取池。如何创建（POST）一个池比？游泳池长什么样？ - 可选字段呢？验证？需要...等？ - “离线”文档呢？
在这篇博文blog.zenika.com/2013/07/11/… 中提到swagger 和hateoas 是互补的。 Swagger 帮助我们记录我们的 API，但资源仍应公开链接以相互导航。
对此有任何启示吗？我在这里遇到了类似的问题stackoverflow.com/questions/38694734/…

标签： rest swagger swagger-ui spring-hateoas

【解决方案1】：

我建议放弃招摇并使用像Postman 这样的restclient。 Postman 使 spring-hateoas 提供的链接可点击，因此您可以快速浏览 API。如果您想提供一些额外的信息/文档，您可以将这些请求保存到 Postman 中的请求集合中并将其导出以进行分发。在我尝试了几种用于 rest api 的文档工具后，包括 raml、swagger、apiary，最后是 Postman-collections 与 hataos 的组合，我发现后者是我最满意的一个。

【讨论】：

【解决方案2】：

使用 Spring Data REST 2.4.0.RELEASE，您现在拥有多种形式的元数据：

ALPS
JSON Schema
通过 spring-data-rest-hal-browser 模块安装 HAL 浏览器并通过超媒体浏览

【讨论】：

【解决方案3】：

隐藏它的唯一合理方法是从模型本身隐藏它（有几种方法可以做到这一点，但如果你使用 Spring MVC，我不确定 swagger-springmvc 支持什么）。

理论上你可以破解 swagger.js 来隐藏它，但这是一次冒险。

【讨论】：

【解决方案4】：

Spring RestDocs 在构建时考虑到了超媒体。它可以在“生成的文档”领域提供与 swagger 相同的好处，但不是基于 URL。

http://docs.spring.io/spring-restdocs/docs/current/reference/html5/#getting-started-build-configuration

努力输出更符合 githubs docs (Hyermedia'd) 的内容。

https://developer.github.com/v3/#current-version

【讨论】：

【解决方案5】：

任何人都看过 HAL 浏览器

http://api.opensupporter.org/hb2/browser.html#/api/v1

它有助于可视化资源之间的关系网络，因此不一定显示资源的请求示例，但确实有显示文档的区域。

我的想法是，在某种程度上，让 Hateos 实现自我记录是一种更简单的方法。也许其中一个超媒体链接可能是一个招摇的网站或可接受的值可能在我上面提到的文档中。

【讨论】：

【解决方案6】：

不要扩展ResourceSupport。相反，对于输入模型使用 POJO Pool，对于响应使用 org.springframework.hateoas.Resource(s)<Pool>，它包装了您的 POJO 并允许定义链接。

【讨论】：