Api-blueprint: 支持 JSON-RPC 的 URI 重载

转移到 apiary.io。

@rodriguise在哪里可以找到有关此问题的信息？ 我也有同样的想法，支持类似 RPC 的 API 将是一个很好的功能。

@rodriguise我也对这个功能很感兴趣，你能告诉我在哪里可以了解这个问题吗？

@adammbalogh @SvyatoslavVasiliev你们

@pksunkara当然。
我有根据JSON-RPC 2.0 Specification设计的 API，例如：

POST http://somehost.com/rpc_api

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "entity.get",
  "params": {
    "filter": {
      "filters": [
        {
          "field": "name",
          "operator": "eq",
          "value": "Bob"
        },
        {
          "field": "age",
          "operator": "eq",
          "value": 25
        }
      ],
      "condition": "and"
    }
  }
}

这样的 API 只有一个方法组的 URL，其中方法的名称包含在 body 中，在“method”参数中。
由于以路径为中心的语言结构，当前的蓝图实现不允许描述此类 API。

嗨@pksunkara ，你有这方面的消息吗？
我曾尝试使用其他渲染工具（例如 aglio）代替 apiary，与 apiary 相比，它们正确地表示了文档。 但是这些工具不支持将某些功能（如属性）呈现为单独的部分。
如果您能帮助解决我的问题，那就太好了。

嘿@SvyatoslavVasiliev所以如果我没看错的话，对 JSON RPC 的支持属于https://github.com/apiaryio/api-blueprint/issues/289，尽管从技术上讲该协议仍然是 HTTP。

将资源和操作定义与 URI 和 HTTP 方法解耦也应该有助于这种情况。

这有意义吗？ 请参阅 #289 以获取更多详细信息

嗨@zdne ，
我试图理解#289，但我无法完全理解它。
我的 API 使用带有 JSON 正文的 HTTP 作为传输，但它只有一个 URL 并且只使用 HTTP POST。 “方法”参数中包含的有关资源和方法的所有信息到正文中。
例如，获取实体：
{ "jsonrpc": "2.0", "id": 1, "method": "entity.get", "params": { "filter": { "filters": [ { "field": "name", "operator": "eq", "value": "Bob" }, { "field": "age", "operator": "eq", "value": 25 } ], "condition": "and" } } }

删除实体：
{ "jsonrpc": "2.0", "id": 1, "method": "entity.delete", "params": { "id": "123" } }

这两种方法都称为 HTTP POST http://myservice.com/rpcapi

到目前为止，我还没有找到一种现代且实用的方式来记录 JSON-RPC API（我也可以用它来生成测试）。 我的希望是 API Blueprint，但它似乎并没有得到真正的支持。 有没有人知道这个 API Blueprint 的未来计划，或者对支持这个的不同结构/工具有什么建议？

@Dynom我可以给几个建议。
您可以尝试为 api 蓝图使用 Aglio 渲染，它不会渲染属性部分，但会正确显示文档的结构。
另一个工具是API Doc ，我目前正在测试它，它似乎很合适。

谢谢@SvyatoslavVasiliev我不想使用内联文档解决方案，而且 API Doc 宣传它是用于 RESTful 服务的，所以我不确定从长远来看我们是否能从中得到很多。