apiblueprint - 如何在 JSON-RPC 中使用 apiary

Question

我正在尝试使用 apiary.io 来记录基于 JSON-RPC 的 API。我可以格式化页面，但控制台根本不起作用。

使用 JSON-RPC，您通常只有 1 个 URI，我们的 API 就是这种情况。因此，在尝试定义方法时，蓝图编辑器会发出警告

Action with method POST already defined...

我想我可以忽略这一点，但在测试时在 apiary 控制台中它只会返回定义的第一个操作的示例响应。有没有人可以解决这个问题？

Answer 1

根据我从 JSON-RPC规范和示例中了解到的情况，多个请求和响应可能比POST多次定义端点更适合您。

# My API

## JSON-RPC [/endpoint]

### Doing something [POST]
+ Request Sum of numbers (application/json-rpc)

        {"method": "sum", "params": {"a":3, "b":4}, "id":0}

+ Response 200 (application/json-rpc)

        {"result": 7, "error": null, "id": 0}

+ Request Posting a message (application/json-rpc)

        {"method": "postMessage", "params": ["Hello all!"], "id": 99}

+ Response 200 (application/json-rpc)

        {"result": 1, "error": null, "id": 99}

缺点：您的 API 将被压缩到一个或两个端点中，并且单个请求在 ToC 中不可见。

优点： Apiary 模拟服务器中的请求-响应配对逻辑将允许您使用一些策略（也在上面链接的页面上描述）来调用与第一个不同的响应。但是，由于这些策略（在发布此答案时）仅适用于标头或状态代码，并且它们不检查传入请求的有效负载正文，因此您可能仍然无法轻松区分控制台中的请求。

可能的解决方法是为您的请求提供额外的标头，例如X-Request: 1,X-Request: 2等，以便模拟服务器可以区分它们并返回正确的响应。

Answer 2

您可以在 api 端点 url 中使用带有锚点、唯一片段路径的技巧。

# Group Awesnome JSON-RPC API

## Entity A [/#A]
### Procedure A [POST]
### Procedure B [POST]

## Entity B [/#B]
### Procedure C [POST]
### Procedure D [POST]