如何使用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规范中有什么方法可以满足这种需求而不会丢失单个资源表示？

来源

2016-12-14 Delmo

我的答案在下面。您可能还想看看我们设计的RAPID-ML，以使规范数据模型具有高度适应性，从而更容易在各种API中重复使用和标准化：http://rapid-api.org/rapid-ml –

从扬鞭-的OpenAPI 2.0 spec，readonly定义如下：

声明的属性为 “只读”。这意味着它可以作为响应的一部分发送给，但不能作为请求的一部分发送。标记为只读属性为true的属性不应位于所定义模式的必需列表中。默认值为false。

由于该规范说，一个只读属性不应要求，有什么readonly + required应该是指没有明确的语义。

（它可能已经合理地说，readonly + required意味着它需要的响应，但仍从请求排除。事实上，有一个open issue，使这一变化，它看起来就像是正在考虑OpenAPI 3.0 ）

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

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

现在，你需要为这些不同的情况不同的模式。由于described here，您可能可以使用allOf组合构建这些架构更多DRY。

来源

2016-12-14 21:28:41

如何使用OpenAPI规范

回答

相关问题