来自 Spring Hateoas 的文档 HAL“_links”（带有招摇）？ [关闭]

我想为我的客户开发团队记录一个 REST 服务。

所以我添加了一些Links from Spring-Hateoas到我的资源 API，并插入其中swagger-springmvc @Api...注释来记录所有内容，并为我的 Angular 团队提供良好的 API 参考，以便能够理解我的 REST 服务。

问题是swagger无法发现哪些链接是可能的，只是给我一大堆Links而不说它们可能的值。

这是一个（简单的）例子。 Swagger 检测到：

Model Schema
CollectionListResource {
    collections (array[CollectionResource]): All available collections,
    links (array[Link]): Relations for next actions
}
CollectionResource {
    collectionId (string): Collection Unique Id,
    name (string): Human readable collection name,
    links (array[Link]): Relations for next actions
}
Link {
    rel (string, optional),
    templated (boolean, optional),
    href (string, optional)
} 

事实上我在 HAL 中得到了：

 {"collections":
    [{"collectionId":"5370a206b399c65f05a7c59e",
      "name":"default",
       "_links":{ [
           "self":{
              "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
            },

           "delete":{
              "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
            }
        ]}
       }, ...]}   

我尝试过延长Link and ResourceSupport有它们的注释版本，但这使我无处可去。

有没有一种方法/工具可以用来生成一个好的 API 文档，告诉我self关系是获取内容，并且delete关系是删除集合？

我喜欢 swagger，因为它有良好的 UI，但如果它有助于获得文档，我不介意更改我的文档工具really完全的。

我最终可以考虑将 spring-hateoas 更改为另一个链接生成器，但我不确定现在是否有更好的工具可用。

Swagger-UI 本身并不是超媒体意识 https://github.com/swagger-api/swagger-core/issues/97;或者至少其局限性在于它只能从顶级 api 导航到 api 列表。这在规范的 v2.0 中也没有太大变化，显着增加了带外文档的外部文档链接。

你需要的是一个混合体哈尔浏览器 http://haltalk.herokuapp.com/explorer/browser.html#/和swagger-ui https://github.com/swagger-api/swagger-ui。正如您正确指出的那样，“删除”一词与其在集合资源上下文中的含义之间存在语义差距。 HAL 使用居里和可选的配置文件的组合ALPS http://alps.io/spec/来弥补这一差距。居里只不过是链接关系的命名空间版本，因此它们不会与其他域发生冲突。Restful Web API http://shop.oreilly.com/product/0636920028468.do是了解更多有关这些想法以及如何设计媒体类型的绝佳资源。这Spring数据休息项目 http://spring.io/blog/2014/07/14/spring-data-rest-now-comes-with-alps-metadata还有一个很好的例子说明如何实现这一目标。

• 我认为有效的方法之一是调整招摇规范 https://github.com/swagger-api/swagger-spec/支持面向操作的视图而不是面向 api 列表的视图，这在您可能使用的时间范围内实际上是不可能的。
• 使用现有的 RFC，例如rfc5023 https://www.rfc-editor.org/rfc/rfc5023对“编辑”资源的含义有一个共同的理解。
• 最后，如果没有任何标准链接关系表达操作的意图，请定义您自己的应用程序特定语义，为这些应用程序特定链接关系提供文档。这样，您的服务的客户将对您的应用程序上下文中的这些关系有一个共同的理解。

下面的示例演示并结合了这些方法。

{"collections":
[{"collectionId":"5370a206b399c65f05a7c59e",
  "name":"default",
  "curies": [
       {
          "name": "sw",
          "href": "http://swagger.io/rels/{rel}",
          "templated": true
       },
       {
          "name": "iana",
          "href": "https://www.rfc-editor.org/rfc/rfc5023",
          "templated": false
       },
       {
          "name": "col",
          "href": "http://localhost:9080/collections/{rel}",
          "templated": false
       }
   ],
   "_links":{ [
        "self":{
          "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
        },
        "sw:operation":{
          "href":"http://localhost:9080/api-docs/collections#delete"
        },
        "sw:operation":{
          "href":"http://localhost:9080/api-docs/collections#search"
        },
        "sw:operation":{
          "href":"http://localhost:9080/api-docs/collections#update"
        },
        "iana:edit":{
          "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
        },
        "col:delete": {
          "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
        }
    ]}
   }, ...]} 

因此，从最通用到最具体，解决方案（按顺序）是

• iana 限定链接具有特定含义，在本例中，“编辑”具有每个宁静客户端都可以实现的非常特定含义。这是一种通用的链接类型。
• sw 限定的链接关系也有特殊的含义，它暗示了 swagger api 文档中操作的 href 深层链接。
• col 限定链接是只有您的应用程序知道的特定于应用程序的链接。

我知道这并不能准确回答您的问题，并且这个领域的工具仍在不断发展。希望这可以帮助。

免责声明：我是其中之一核心维护者 https://github.com/martypitt/swagger-springmvc/graphs/contributors of 春狐 https://springfox.io这是一个 Spring 集成解决方案，可以轻松提供 swagger 服务描述。因此，非常欢迎您提供有关如何解决此问题的任何反馈！