Question

我想描述一个API，其中包含允许在POST项目时定义值的不同方法的字段，但只能以一种特定方式在字段中输出。

例如，我可能想要描述一个API，其中可以像这样创建或更新项目：{"name": "Task", "due": "2014-12-31"}或像这样：{"name": "Task", "due": {"$date": 1419984000000}}，但它只会从API中返回第一种方式。

POST / PUT的架构因此可以是：

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "oneOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "object",
                    "properties": {
                        "$date": {
                            "type": "number"
                        }
                    },
                    "required": ["$date"],
                    "additionalProperties": false
                }
            ]
        }
    }
}

而通过GET访问的模式会更简单：

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "type": "string",
            "format": "date"
        }
    }
}

API的消费者知道他们只需要考虑一种可能的输出方法而不是所有输出方法，这将是一件好事。

是否有任何可接受的标准方法在JSON Hyper-Schema的上下文中指定不同的模式？我已经考虑过通过"links"属性来指定这些差异，但我不知道我将在"rel"下定义这些模式，它看起来非常非标准。

Answer 1

如果我理解正确，并且您希望为每个操作指定一个模式，则可以使用标准超模式执行此操作。让我们看一下后期操作的例子：

{
  "description": "create an item.",
  "href": "/items",
  "method": "POST",
  "rel": "create",
  "schema": {
    "$ref": "#/api/createitem"
  },
  "title": "Create an item"
}

所需的实际架构在“schema”属性中通过“$ ref”引用。

如果您还想描述响应类型，则可以使用“targetSchema”属性。请注意，这只是建议性的（因为它是explained in the docs）

JSON Hyper-Schema：GET和POST的不同模式

1 个答案: