来自Spring Hateoas的文件HAL"_links"(带着招摇)？

Question

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

所以我加了一些Links从Spring-Hateoas我的资源API,并插入到它swagger-springmvc @Api...注解来记录一切,使一个很好的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本身并不是超媒体感知的 ; 或至少它的限制因为它只能从顶级api导航到api列表.在规范的v2.0中也没有太大变化,显着增加了对带外文档的外部文档的链接.

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

• 我认为可行的方法之一是调整swagger规范以支持面向操作的视图,而不是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限定链接具有特定含义,在这种情况下,"编辑"具有非常特定的含义,每个宁静的客户端都可以实现.这是一种基因化链接类型.
• sw限定链接关系也有特殊含义,它暗示了href与swagger api文档中操作的深层链接.
• col限定链接是仅应用程序知道的特定于应用程序的链接.

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

免责声明:我是springfox的核心维护者之一,它是一个Spring集成解决方案,可以轻松提供swagger服务描述.因此,非常欢迎任何有关您希望如何解决此问题的反馈!