Question

阅读此post（请参阅： 3如何使用单个定义... ）关于使用OpenAPI（Swagger）规范描述REST API，您可以注意如何保持单个资源表示，用于使用 readOnly 属性添加/更新和获取资源，而不是一个表示获取（获取集合项）和另一个表示添加（POST到集合）。例如，在以下用户单个表示中， 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规范中有任何方法可以满足这种需求而不会丢失单个资源表示吗？

Answer 1

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

将属性声明为“只读”。这意味着它可以被发送作为回复的一部分但不得作为请求的一部分发送。标记为readOnly为true的属性不应该是必需的已定义架构的列表。默认值为false。

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

（可能有理由说readonly + required意味着它在响应中是必需的，但仍被排除在请求之外。实际上有一个open issue来实现这一点改变，看起来它正在考虑OpenAPI 3.0。）

不幸的是，单个模式无法在请求中创建所需的属性，但在响应中是可选的（或不允许的）。

（同样，有一个open issue提出了一个“只写”修饰符，可能正在考虑下一个版本。）

目前，您需要为这些不同的案例创建不同的模式。作为described here，您可以使用allOf合成使这些架构更DRY。

如何使用OpenAPI规范

1 个答案: