Question

我正在尝试使用RAML具体描述各种加密货币交换API 谁，它们都使用不同的格式（非标准化）来呈现和记录他们的API。我很容易为RESTful API做这个（因为这主要是我理解的RAML），但是对于使用JSON-RPC而不是https的API来说这很困难。

首先......这可能和/或可行吗？

如果可行和/或可行，以下是正确的方法吗？它似乎有限，因为我不知道枚举可能的方法及其各自的参数的方法，我只能声明有一个方法参数。

正如David Dossot所建议的那样，我尝试使用JSON模式而不是queryParameters。这是我的尝试（我仍然没有看到枚举/描述API的各个方法的方法，我只能表达有一个方法关键字，它是一个字符串（类似于我的限制） queryParameters route）。

#%RAML 0.8

title: BTC-China API
baseUri: https://data.btcchina.com/data/

baseUri: https://api.btcchina.com/api_trade_v1.php

/api_trade_v1.php:
  post:
    description: The JSON-RPC BTC-China API.
    headers:
      Authorization:
        description: |
          Blah blah

        example: Basic PGFjY2Vzc2tleT46PGhhc2g+
    body:
      application/json:
        schema: |
          {
           "$schema" : "http://json-schema.org/draft-04/schema#",
           "title": "JSON-RPC Request",
           "description" : "A JSON-RPC request to the BTC-China API.",

           "type" : "object",
           "required" : ["jsonrpc", "method"],
           "properties" : {
             "jsonrpc" : { "enum" : ["2.0"] },
             "method" : {
               "type" : "string"
              },
              "id" : {
                "type" : "number"
              },
              "params" : {
                "type" : ["array", "object"]
              }
            }
          }

    responses:
       200:
          body:
            application/json:
              example: |
                {"result":12345,"id":"1"} 

        401:
          body:
            text/plain:
              example: 401 Unauthorized - invalid access key

现在我正在使用模式，我仍然没有看到可以枚举或描述API的各个方法的方法。

2014年8月13日更新：

尝试使用JSON $ refs和子模式（仍然遇到如何将方法与其相关参数链接以及如何描述方法等问题，因为JSON Schema v4只有3个验证参数string（该方法在JSON-RPC中的类型，它不是一个对象），maxLength，minLength和pattern。没有足够的表达方式来解释方法是什么/做什么以及它的选项/可用参数）

body:
  application/json:
    schema: |
      {
       "$schema" : "http://json-schema.org/draft-04/schema#",
       "title": "JSON-RPC Request",
       "description" : "A JSON-RPC request to the BTC-China API.",

       "type" : "object",
       "required" : ["jsonrpc", "method"],
       "properties" : {
         "jsonrpc" : {
           "enum" : ["2.0"]
         },
         "method" : {
           "type" : "string",
           "oneOf" : [
               { "$ref": "#/definitions/getbalance" },
               { "$ref": "#/definitions/withdrawal" },
               { "$ref": "#/definitions/depositaddress" }
             ]
          },
          "id" : {
            "type" : "number"
          },
          "params" : {
            "type" : ["array", "object"]
          }
        }
        "definitions" : {
          "getbalance": {},
          "withdrawal": {},
          "depositaddress": {}
      }

Answer 1

不要使用queryParameters来尝试描述JSON-RPC协议中使用的JSON主体实体，而是使用JSON Schema。

阅读此内容也可能有所帮助：http://www.jsonrpc.org/historical/json-schema-service-descriptor.html

Answer 2

您可以使用另一个规范描述您的JSON RPC服务：

RAML功能非常强大，适用于常见用途。例如，如何使用JSON-WSP？

使用RAML通过HTTPS描述JSON-RPC服务

2 个答案: