Swagger 我应该在什么时候使用$ref而不是openapi中的对象id

我正在使用Swagger在OpenAPI中处理一个模式，我不确定是否误用了

$ref

元素。我有一个

用户

模型和一个

项目

模型，类似于

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"
        ...

关于

$ref

元素具体是什么，我在OpenAPI规范文档中没有看到太多内容，但在OpenAPI扩展

$ref

元素的JSON模式文档中，我发现了该项的以下描述：

描述$ref最简单的方法是用它所指向的对象在逻辑上替换它

在上面的例子中，我只想引用发布项目的用户。如果项目模型就是这样做的，那么在项目模型中包含关于用户的所有信息似乎是不必要的。如果只使用

用户id的uuid的
字符串
元素会更好吗？或者它是正确的吗？如果是这样的话，将字段命名为
user
比命名为
user\u id
更常见吗

编辑：
我意识到困扰我的核心是是否存在递归引用。如果一个用户对项目有一个
$ref
数组，但是一个项目对用户也有一个
$ref
数组，那么替换（如果是这样做的话）将无限地将每个模型嵌入到另一个模型中。我假设这在实践中不会发生，假设
$ref
只是一个指向模型的指针？
在您的示例中，将
用户ID
定义提取到它自己的模式中可能是有意义的（假设只显示
用户ID
，而不是整个
用户
对象），这样就更清楚发生了什么：

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