如何在微服务架构（HAL、ALPS）中为 Restful 服务正确设置文档

Question

我已经阅读了很多关于如何正确设置微服务的文章，而且我一直对一些较新的概念很感兴趣，包括：HAL、ALPS 和 HAL 浏览器。我在历史上记录了利用 Swagger UI 的事情，但是，我开始明白以 URL 为中心不是正确的方法，我应该围绕资源和链接组织文档，这就是新技术为了。我对这些较新的概念存在很多知识空白，所以我想正确理解这些技术如何协同工作，以便在我了解每一项技术时可以将它们融入这个难题中。

我目前的理解是：

HAL - 是 JSON 之上的一种附加格式，可让您通过链接浏览 API。

ALPS - 这是 JSON 之上的一种附加格式，可以让我提供基于英语的描述来帮助描述我的资源

HAL 浏览器 - Swagger UI 替换资源和 Link 中心文档。与 HAL 和 ALPS 一起工作？

我目前对这些技术的理解是否准确或在某些方面有所欠缺？同样在实施方面，我并不完全理解 ALPS 和 HAL 如何相互作用。我知道 hal+json 格式和 alps+json 格式，但我还没有看到 hal+alps+json 格式。

我想澄清的最后一个方面是我应该如何公开这些资源。通常我总是关注非常精简的 json 消息正在发送预期的 hal+json 格式，或者我应该将这些端点托管在另一个 URL 专门用于类似于 swagger / HAL 的文档浏览器？

Answer 1

我在每个微服务中都有自己的 api 文档 url。例如：http://myservice1domain:8080/swagger-ui.html。我没有用过阿尔卑斯山。此外，我认为您不必或可以专门公开 HAL 类的东西，因为它们与响应数据绑定。无论如何，HAL 作为示例请求主体和响应 json 正确

大摇大摆地向用户公开

Answer 2

伙计！你想在这里看到的信息太多了。让我尝试逐步解释。

以文档为中心意味着服务之间的转换，是的，它应该被称为网络上的语义共享信息（或理解为数据类型）。

步骤：1 用于具有数据类型元数据和标准数据类型的服务的协议 (http) 可以是任何形式的超媒体，即 HTML、XML、JSON、HAL 等。例如下图的JSON，就是一个根文档，里面有link。 'todos' 和 'profile' 都只是基于 HAL 的超媒体 link，而 HAL 只会增强您当前的 API。

{ "_links" : {
    "todos" : {
      "href" : "http://localhost:8080/todos"
    },
    "profile" : {
      "href" : "http://localhost:8080/alps"
    }
  }
}

请注意，只有 link 可能的资源 linking 可以指向资源的语义。 HAL 的主要焦点只是通过 links，属性 and/or 嵌入 linking resources/templates。上面解释的可供性主要是 links 协议级别的共享数据类型。

步骤：2 ALPS 是应用程序级别的启示，这意味着在上面 JSON 我知道 Todo 是什么但如何与之交互？要与 Todo 交互，需要有应用程序级别的状态转换。考虑下面的 'todo' JSON，它从 link 导航并显示详细的额外关键字，例如 'descriptors' 和 'Type'（SEMANTIC、SAFE、UNSAFE 等）。

'id' 属性成为表示标识符。这些是设置或规则以应用独立的 ALPS 状态和转换。

{ "version" : "1.0",
  "descriptors" : [ {
    "id" : "todo-representation",
    "descriptors" : [ {
      "name" : "description",
      "doc" : {
        "value" : "Details about the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "title",
      "doc" : {
        "value" : "Title for the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "id",
      "type" : "SEMANTIC"
    } ]
  }, {
    "id" : "get-todos",
    "name" : "todos",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "create-todos",
    "name" : "todos",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "delete-todo",
    "name" : "todo",
    "type" : "IDEMPOTENT",
    "rt" : "#todo-representation"
  }, {
    "id" : "patch-todo",
    "name" : "todo",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "get-todo",
    "name" : "todo",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  } ]
}

一些link值得详细检查slides about ALPS and Rest Example。希望这对您的理解有所帮助。

如何在微服务架构（HAL、ALPS）中为 Restful 服务正确设置文档

How to properly setup documentation for Restful services in a micro-service architecture (HAL, ALPS)

java

spring

spring-data

spring-data-rest

microservices