首页 文章

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

提问于
浏览 次
10

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

所以我从 Spring-Hateoas 添加了一些 Links 到我的资源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 和 ResourceSupport 以获得它们的注释版本，但这导致我无处可去 .

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

我喜欢swagger的优秀用户界面，但是如果它的帮助文档真的完整，我不介意更改我的文档工具 .

我最终可能会想到为另一个链接生成器改变spring-hateoas，但我不确定现在有更好的工具可用 .

spring spring-mvc documentation swagger spring-hateoas

1 回答

  • 12

    Swagger-UI本身不是hypermedia aware;或至少它的限制因为它只能从顶级api导航到api列表 . 在规范的v2.0中也没有太大变化，显着增加了对带外文档的外部文档的链接 .

    你需要的是HAL browser和swagger-ui的混合体 . 正如您正确指出的那样，单词"delete"与集合资源上下文中的含义之间存在语义上的差异 . HAL使用curies和可选的配置文件ALPS的组合来弥补这一差距 . Curies只是链接关系的命名空间版本，因此它们不会与其他域冲突 . Restful Web APIs是一个很好的资源，可以更多地了解这些想法以及如何设计媒体类型 . spring data rest project也有一个如何实现这一目标的很好的例子 .

    • 我认为其中一种方法是调整swagger specification以支持面向操作的视图，而不是api列出面向视图，在您可能使用的时间范围内实际上不可能 .

    • 使用像rfc5023这样的现有RFC来共享对资源意味着什么的理解 .

    • 最后，如果没有标准链接关系表达操作的意图，请定义您自己的应用程序特定语义，为这些特定于应用程序的链接关系提供文档 . 这样，您的服务的客户将在您的应用程序的上下文中共享这些关系 .

    以下是演示和组合这些方法的示例 .

    {"collections":
[{"collectionId":"5370a206b399c65f05a7c59e",
  "name":"default",
  "curies": [
       {
          "name": "sw",
          "href": "http://swagger.io/rels/{rel}",
          "templated": true
       },
       {
          "name": "iana",
          "href": "http://tools.ietf.org/html/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限定链接具有特定含义，在这种情况下"edit"具有非常特定的含义，每个宁静的客户端都可以实现 . 这是一种基因化链接类型 .

    • sw限定链接关系也有特殊含义，它意味着href与swagger api文档中操作的深层链接 .

    • col限定链接是仅应用程序知道的特定于应用程序的链接 .

    我知道这并没有准确地回答你的问题，而且这个领域的工具仍在不断发展 . 希望这可以帮助 .

    免责声明：我是springfox的springfox之一，它是一个 spring 集成解决方案，可以轻松提供昂首阔步的服务描述 . 因此，非常欢迎任何有关您希望如何解决此问题的反馈！

    回复于

相关问题