0

阅读这篇关于使用 OpenAPI (Swagger) 规范描述 REST API的帖子（请参阅：3 How to use a single definition when... ），您可以注意如何使用readOnly属性保留单个资源表示以添加/更新和获取资源有一种表示用于获取（获取集合项）和另一种表示用于添加（POST 到集合）。例如，在下面的 User 单一表示中，id是一个只读属性，这意味着它不会在创建用户时在表示中发送，而是在检索用户时存在。

"User":
{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer",
            "format": "int64",
            "readOnly": true
        },
        "company_data": {
            "type": "object",
            "properties": {
                .
                .
                .
            },
            "readOnly": false
        }
    }
}

保持资源表示列表尽可能短真的很干净而且很好，所以我想保持单一资源表示方法，但我面临的问题是：当一个属性对于输入来说是强制性的时如何管理required ? 假设我需要在创建用户时根据需要设置company_data (POST /users/)，但在检索用户时不需要设置 (GET /users/{user_id})。OpenAPI 规范中有什么方法可以在不丢失单一资源表示的情况下满足这种需求？

4

1 回答 1

2

从 Swagger-OpenAPI 2.0 规范，readonly定义如下：

将属性声明为“只读”。这意味着它可以作为响应的一部分发送，但不能作为请求的一部分发送。标记为 readOnly 为 true 的属性不应出现在已定义模式的必需列表中。默认值为假。

由于规范说不应该要求只读属性，因此没有定义readonly+required应该表示的语义。

（可以合理地说readonly+required表示它在响应中是必需的，但仍被排除在请求之外。事实上，进行此更改存在一个未解决的问题，并且看起来它正在考虑用于OpenAPI 3.0。）

不幸的是，单一模式无法在请求中设置属性，但在响应中是可选的（或不允许的）。

（同样，有一个未解决的问题提出了“只写”修饰符，可能正在考虑下一个版本。）

现在，您需要为这些不同的情况创建不同的模式。如此处所述，您可以使用组合使这些模式更加干燥allOf。

于 2016-12-14T21:28:41.600 回答