Question

我正在使用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只是指向模型的指针？

Answer 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规范允许循环引用，因此您对指针的类比是合理的。

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

1 个答案: