我应该何时使用$ ref与Open API中的对象ID

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元素 - 我发现了该项的以下描述：

描述$ 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

但是没有什么可以阻止你创建一个直接的$ref到#/components/schemas/User/properties/id，只要指向的是有效的OpenAPI schemaObject。

JSON Reference和OpenAPI规范允许循环引用，因此您对指针的类比是合理的。