我正在使用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
只是指向模型的指针?
答案 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规范允许循环引用,因此您对指针的类比是合理的。