我有以下 OpenAPI 3 架构:
{
...,
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true
},
"name": {
"type": "string"
}
}
},
"Report": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true
},
"user": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
现在,如果我为 User 和 Report 指定 GET 请求,一切看起来都不错。用户的 POST 请求也有效。但是,对 Report 的 POST 请求不起作用。Report POST 请求的正文应如下所示:
{
"user": {
"id": 1
}
}
因此不应指定“name”属性,因为它只是对已存在的用户的引用,并将根据 id 进行匹配。
是否可以编写 Report POST 请求,以便它理解只应指定用户的 id?还是我被迫创建两种不同的报告模式,一种用于 GET 请求,一种用于 POST 请求?
有几种方法可以解决这个问题。您可以专门为 POST 创建一个定义,也可以将您的User
定义拆分为更多原子组件以供重用。
将您的报告user
定义构建为如下所示:
"user": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true
}
}
这样做的好处是快速简便,不会影响您定义的其他领域。但这会导致大量代码重复,并且未来对设计的任何更改都要求您确保不会遗漏任何这些特殊定义。
您有两个不同的属性,它们具有不同的用途,在多个定义中使用。这是一个很好的参考人选。将您的User
定义拆分为多个模式。像这样的东西:
"schemas": {
"userId": {
"type": "integer",
"format": "int64",
"readOnly": true
},
"userName": {
"type": "string"
},
"User": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/userId"
},
"name": {
"$ref": "#/components/schemas/userName"
}
}
}
这使您可以重用userId
你Report
有着怎样的相同的定义id
实际上是。当您开始将定义扩展为更大的 API 时,这种方法可能开始变得难以阅读,但随着您的 API 形状随着时间的推移而变化,这种方法更易于维护。请注意,这也有助于定义用户 ID 和报告 ID 之间的区别,虽然它们共享相同的名称,但可能拥有不同的数据,并且随着时间的推移可能会有不同的规则。
本文收集自互联网,转载请注明来源。
如有侵权,请联系 [email protected] 删除。
我来说两句