我应该何时使用$ ref与Open API

时间:2017-09-27 05:06:39

标签: swagger openapi

我正在使用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"
        ...

我在Open API规范文档中没有看到$ref元素具体是什么,但在JSON Schema文档中 - Open API扩展了$ref元素-I'我找到了该项目的以下描述:

  

描述$ ref的最简单方法是从逻辑上取代它所指向的东西。

在上面的例子中,我只想引用发布项目的用户。似乎没有必要在项目模型中包含有关用户的所有信息,如果这正是它正在做的事情。如果只有string的uuid的user_id元素,那么更好的做法是什么?或者它是否正确?如果是这种情况,将字段命名为user而不是user_id会更常见吗?

修改: 我意识到困扰我的是如果有递归引用的话。如果用户有一个$ref到项目的数组,但是项目有一个$ref到用户的数组,那么替换(如果它正在做的那样)将无限地将每个模型嵌入到另一个模型中。我假设在实践中不会发生这种情况,假设$ref只是指向模型的指针?

1 个答案:

答案 0 :(得分:1)

在您的示例中,将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 Reference和OpenAPI规范允许循环引用,因此您对指针的类比是合理的。