什么时候应该使用$ ref与Open API中的对象ID

我正在使用Swagger处理OpenAPI中的模式，并且我不确定是否滥用了$ref元素。我有一个User模型和Project模型，类似于像

User: 
     type: object 
     properties: 
     id: 
      type: string 
      format: uuid 
     name: 
      type: string 
     ... 
Project: 
     type: object 
     properties: 
     id: 
      type: string 
     user_id: 
      $ref: "#/components/schemas/User" 
     ...

我看不出有任何的开放API规范的文档说明$ref元素是什么特别的，但是JSON模式的文档-的其开放的API扩展$ref元素 - 我发现该项目的如下描述：

描述$裁判最简单的方法是，它就会在逻辑上与它指向的东西所取代。

在上面的例子中，我只想引用发布项目的用户。似乎没有必要在项目模型中包含有关用户的所有信息，如果这正是它所做的。 user_id的uuid的string元素会是更好的练习吗？还是它是正确的？如果是这种情况，命名user而不是user_id是否更常见？

编辑：我意识到困扰我的是如果有递归引用。如果用户有一个$ref到数组的项目，但项目中有一个数组$ref给用户，替换（如果是这样做的话）会无限地将每个模型嵌入到另一个模型中。我认为这在实践中不会发生，假设$ref只是一个指向模型的指针？

来源

2017-09-27 cchapman

在您的例子可能是有意义提取userId定义成自己的模式（假设它是userId只是出现，而不是整个User对象），那么它是更清楚发生了什么事情：

components: 
    schemas: 
    User: 
     type: object 
     properties: 
     id: 
      $ref: '#/components/schemas/userId' 
     name: 
      type: string 
     ... 
    Project: 
     type: object 
     properties: 
     id: 
      type: string 
     user_id: 
      $ref: "#/components/schemas/userId" 
     ... 
    userId: 
     type: string 
     format: uuid

但是，只要指向的内容是一个有效的OpenAPI schemaObject，就没有什么能够阻止您创建直接的$ref到#/components/schemas/User/properties/id。

JSON参考和OpenAPI规范允许循环引用，所以您的指针类比是合理的。

来源

2017-12-20 18:56:46 MikeRalphson

什么时候应该使用$ ref与Open API中的对象ID

回答

相关问题