如何使用OpenAPI规范
读取此post(请参阅:3如何在使用OpenAPI(Swagger)规范描述REST API时使用单一定义...),您可以注意如何使用OpenAPI使用readOnly属性保留一个资源表示,用于添加/更新并获取资源,而不是使用一个表示获取(GET集合项),另一个用于添加(POST集合)。例如,在以下用户单一表示中,ID是是只读属性,这意味着在创建用户时不会在表示中发送它,它将在用户检索时出现在表示中。如何使用OpenAPI规范
"User":
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true
},
"company_data": {
"type": "object",
"properties": {
.
.
.
},
"readOnly": false
}
}
}
这是非常干净,漂亮,保持资源的代表名单尽可能短,所以我想保持单一资源表示方法,但我面临这样做的问题是:如何管理要求只有输入属性是强制性的?假设我需要在创建用户(POST/users /)时根据需要设置company_data,但在检索用户(GET/users/{user_id})时不需要。 OpenAPI规范中有什么方法可以满足这种需求而不会丢失单个资源表示?
从扬鞭-的OpenAPI 2.0 spec,readonly
定义如下:
声明的属性为 “只读”。这意味着它可以作为响应的一部分发送给 ,但不能作为请求的一部分发送。 标记为只读属性为true的属性不应位于所定义模式的必需 列表中。默认值为false。
由于该规范说,一个只读属性不应要求,有什么readonly
+ required
应该是指没有明确的语义。
(它可能已经合理地说,readonly
+ required
意味着它需要的响应,但仍从请求排除。事实上,有一个open issue,使这一变化,它看起来就像是正在考虑OpenAPI 3.0 )
不幸的是,单个模式无法在请求中生成所需的属性,但在响应中可选(或不允许)。
(同样,有一个open issue提出了“只写”修改,可能在考虑下一个版本。)
现在,你需要为这些不同的情况不同的模式。由于described here,您可能可以使用allOf
组合构建这些架构更多DRY。
我的答案在下面。您可能还想看看我们设计的RAPID-ML,以使规范数据模型具有高度适应性,从而更容易在各种API中重复使用和标准化:http://rapid-api.org/rapid-ml –