Question

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

所以我从Links添加了一些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)
}

我实际上是在哈尔：

 {"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的混合体。正如你正确指出的那样，单词＆＃34; delete＆＃34;之间存在语义上的差距。以及它在集合资源的上下文中意味着什么。 HAL使用curies和可选的配置文件ALPS的组合来弥补这一差距。 Curies只是链接关系的命名空间版本，因此它们不会与其他域冲突。 Restful Web APIs是了解有关这些想法以及如何设计媒体类型的更多资源。 spring data rest project也是如何实现这一目标的一个很好的例子。

我认为其中一种方法是调整swagger specification以支持面向操作的视图而不是api列表导向视图，在您可能使用的时间范围内实际上不可能。
使用rfc5023之类的现有RFC来共同理解＆＃34;编辑和资源的含义。
最后，如果没有标准链接关系表达操作的意图，请定义您自己的应用程序特定语义，为这些特定于应用程序的链接关系提供文档。这样，您的服务的客户将在您的应用程序的上下文中对这些关系有共同的理解。

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

{"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合格链接具有特定含义，在这种情况下，＆＃34;编辑＆＃34;具有非常具体的含义，每个宁静的客户都可以实现。这是一种基因化链接类型。
sw限定链接关系也有特殊含义，它意味着href与swagger api文档中操作的深层链接。
col限定链接是仅应用程序知道的特定于应用程序的链接。

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

免责声明：我是core maintainers的springfox之一，这是一个弹簧集成解决方案，可以轻松提供昂首阔步的服务说明。因此，非常欢迎任何有关您如何解决此问题的反馈意见！

HAL＆＃34; _links＆＃34;来自Spring Hateoas（带着招摇）？

1 个答案: