文件HAL“_links”从春天的Hateoas（与swagger）？ [英] 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 添加了一些链接到我的资源API，并插入它 swagger-springmvc @Api ... 注释来记录所有内容，并使
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 是无法发现什么链接是可能的，只是给我一大堆链接而不说他们可能的值。
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"
}
]}
}, ...]}
我试图扩展链接和 ResourceSupport 以具有其注释版本，但这导致我无处。
I've tried to extend Link and ResourceSupport to have annoted version of them but this lead me to nowhere.
有没有一种方法/工具可以用来生成一个好的API文档，告诉一个 self 关系是获取内容，并且删除关系是删除集合？
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的好UI，但是如果帮助文档完整完成，我不介意更改我的文档工具。
I liked swagger for its good UI, but I don't mind changing my documentation tool if its help having the doc really complete.
我最终可能会考虑为另一个链接生成器更改春天的仇恨，但我不知道现在有没有更好的工具。
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本身不是超媒体感知;或至少其限制，它只能从顶级apis到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浏览器和 swagger-ui 。正如你正确地指出的那样，在删除这个词与它在收集资源的上下文意义上有一个语义上的差距。 HAL使用了一个组合的咖喱和可选的配置文件 ALPS 来弥合这一差距。柯里斯只不过是链接关系的命名空间版本，所以它们不会与其他领域相冲突。 Restful Web API 是了解更多有关这些想法以及如何设计媒体类型的绝佳资源。 春季资料休息项目还有一个很好的例子，如何实现。
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 ）共享理解/>
- 最后，如果没有一个标准的链接关系表达了动作的意图，请定义您自己的应用程序特定语义，为这些应用程序特定的链接提供文档关系。这样您的服务的客户端将在您的应用程序的上下文中对这些关系有共同的了解。
- 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": "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"
}
]}
}, ...]}
所以从最通用到最具体的，解决方案（按顺序）是
So from most generic to most specific, the solution (in that order) is
- iana合格链接具有特定的含义，在这种情况下，编辑具有非常具体的含义，即每个安静的客户端都可以实现。这是一个通用的链接类型。
- sw限制链接关系也具有特殊意义，这意味着href与swagger api文档中的操作的深层链接。
- col限定链接是仅应用程序知道的应用程序特定链接。
我知道这不能正确回答你的问题，而且这个领域的工具还在不断发展。希望这有帮助。
I know this doesn't answer your question precisely, and the tools in this space are still evolving. Hope this helps.
免责声明：我是 springfox 的rel =nofollow>核心维护者，这是一个弹簧集成解决方案，可以轻松提供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”从春天的Hateoas（与swagger）？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
