spring - 来自 Spring Hateoas 的文档 HAL "_links"( Swagger )？

Question

我想为我的客户开发团队记录一个 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 更改为另一个链接生成器，但我不确定现在是否有更好的工具可用。

Answer 1

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

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

• 我认为可行的方法之一是调整 swagger specification支持面向操作的 View 而不是面向 api 列表的 View ，这在您可能使用的时间范围内实际上是不可能的。
• 使用现有的 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 限定链接具有特定含义，在这种情况下，“编辑”具有非常特定的含义，每个 restful 客户端都可以实现。这是一个通用的链接类型。
• sw限定的链接关系也有特殊的含义，它暗示了swagger api文档中操作的href深层链接。
• col 限定链接是特定于应用程序的链接，只有您的应用程序知道。

我知道这并不能准确回答您的问题，而且该领域的工具仍在不断发展。希望这会有所帮助。

免责声明:我是 core maintainers 中的一员的 springfox这是一个 Spring 集成解决方案，可以轻松提供 Swagger 服务描述。因此，非常欢迎您就如何解决此问题提供任何反馈!