文档 HAL“_links"来自 Spring Hateoas(大摇大摆)? [英] Document HAL "_links" from Spring Hateoas (with swagger)?

问题描述

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

I have a REST service I want to document for my client developing team.

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

So I added some Links from Spring-Hateoas to my resources API, and plugged into it swagger-springmvc @Api... annotations to document everything and make a good API reference for my Angular team to be able to understand my REST service.

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

The problem is that swagger is unable to discover what links are possible, and just give me a big array of Links without saying their possible values.

这是一个(简单的)示例.Swagger 检测到:

Here is a (simple) example. Swagger detects :

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 中:

And I get in fact in HAL :

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

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

我试图扩展 Link 和 ResourceSupport 以拥有它们的注释版本，但这导致我无处可去.

I've tried to extend Link and ResourceSupport to have annoted version of them but this lead me to nowhere.

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

Is there a way/tool I could use to generate a good API doc telling that a self relation is to get the content, and a delete relation is to delete the collection ?

我喜欢 swagger 的良好用户界面，但如果它有助于使文档 真正 完整，我不介意更改我的文档工具.

I liked swagger for its good UI, but I don't mind changing my documentation tool if its help having the doc really complete.

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

I could eventually think of changing spring-hateoas for another link generator, but I'm not sure there is a better tool available right now.

推荐答案

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

Swagger-UI as such is not hypermedia aware; or atleast its limited in that it can ONLY navigate from top level apis to api listings. That has not changed much in v2.0 of the spec either, with the notable addition of linking to external documents for out of band documentation.

您需要的是 HAL 浏览器 和 a href="https://github.com/swagger-api/swagger-ui" rel="nofollow noreferrer">swagger-ui.正如您正确指出的那样，删除"一词与删除"一词之间存在语义差距.以及它在集合资源的上下文中意味着什么.HAL 使用居里和可选配置文件 ALPS 的组合来弥补这一差距.居里只是链接关系的命名空间版本，因此它们不会与其他域发生冲突.Restful Web APIs 是了解这些想法以及如何设计媒体的绝佳资源类型.spring 数据休息项目 也有一个很好的例子来说明如何实现这一点.

What you need is a hybrid of the HAL browser and the swagger-ui. As you rightly pointed out, there is a semantic gap between the word "delete" and what it means in the context of a collection resource. HAL uses a combination of curies and optionally a profile document ALPS to bridge this gap. Curies are nothing but namespaced versions of linked relations so that they dont collide with other domains. Restful Web APIs is a great resource to learn more about these ideas and how to design media types. The spring data rest project also has a great example of how to achieve that.

• 我认为可行的方法之一是调整 swagger 规范支持面向操作的视图而不是面向 api 列表的视图，这在您可能使用的时间范围内实际上是不可能的.
• 使用现有的 RFC，例如 rfc5023 来共同理解什么是编辑";ing 一个资源的意思.
• 最后，如果没有标准链接关系表达操作的意图，请定义您自己的应用程序特定语义，为这些应用程序特定链接关系提供文档.这样一来，您的服务客户就会在您的应用程序上下文中对这些关系有共同的理解.

• One of the ways that I think would work is to adjust swagger specification to support an operations oriented view rather than api listing oriented view, not really possible in the the timeframe that you're possibly working with.
• Use existing RFC's like rfc5023 to have a shared understanding of what "edit"ing a resource means.
• Lastly if none of the standard link relationships express the intent of the action, define your own application specific semantics that provide documentation for these application specific link relationships. That way clients of your service will have a shared understanding of these relations within the context of your application.

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

Below is an example that demonstrates and combines these approaches.

{"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"
        }
    ]}
   }, ...]} 

所以从最通用到最具体，解决方案(按此顺序)是

So from most generic to most specific, the solution (in that order) is

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

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

I know this doesn't answer your question precisely, and the tools in this space are still evolving. Hope this helps.

免责声明:我是 核心维护者之一href="https://springfox.io" rel="nofollow noreferrer">springfox 这是一个 Spring 集成解决方案，可以轻松提供 Swagger 服务描述.因此，非常欢迎您就如何解决此问题提供任何反馈！

DISCLAIMER: I'm one of the core maintainers of springfox which is a spring integration solution that makes it easy to provide swagger service descriptions. So any feedback on how you'd like it to solve this problem is very welcome!

这篇关于文档 HAL“_links"来自 Spring Hateoas(大摇大摆)?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！