将判别器与 allOf 一起使用
Using discriminator together with allOf
我正在尝试使用 swagger-php v2.0 记录一个 api 端点,但未正确生成 swagger 文档。
我的用例是我需要从同一端点接受 2 个不同的有效负载,并且某些键只能出现在给定的上下文中。
至于官方文档,可以使用 discriminator
以及 OpenAPI (Swagger) 规范中给出的 allOf
和 this is the example 来实现。
为清楚起见,我将post此处缩小版本
{
"definitions": {
"FooBar": {
"type": "object",
"discriminator": "type",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"name",
"type"
]
},
"foo": {
"allOf": [
{
"$ref": "#/definitions/FooBar"
},
{
"type": "object",
"properties": {
"unique_to_foo_field": {
"type": "string",
}
},
"required": [
"unique_to_foo_field"
]
}
]
},
"bar": {
"allOf": [
{
"$ref": "#/definitions/FooBar"
},
{
"type": "object",
"properties": {
"unique_to_bar_field": {
"type": "string",
}
},
"required": [
"unique_to_bar_field"
]
}
]
}
}
}
我想将其转换为 swagger-php,我想出的如下,但似乎不正确。求教指正,谢谢
/**
* @SWG\Definition(
* definition="model:FooBar",
* type="object",
* discriminator="type",
* required={"type", "name"},
* @SWG\Property(property="type", type="string"),
* @SWG\Property(property="name", type="string"),
* )
*
* @SWG\Definition(
* definition="model:foo",
* allOf={
* @SWG\Schema(ref="#/definitions/model:FooBar"),
* @SWG\Schema(
* required={"unique_to_foo_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer")
* )
* }
* )
*
* @SWG\Definition(
* definition="model:bar",
* allOf={
* @SWG\Schema(ref="#/definitions/model:FooBar"),
* @SWG\Schema(
* required={"unique_to_bar_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer")
* )
* }
* )
*/
好的,在朋友的帮助下我设法想出了一个答案。
为了其他可能遇到同样问题的人的利益,我发布了我自己的答案。
/**
* @SWG\Post(
* @SWG\Parameter(
* name="Create a foo",
* in="body",
* @SWG\Schema(ref="#/definitions/foo")
* ),
* @SWG\Parameter(
* name="create a bar",
* in="body",
* @SWG\Schema(ref="#/definitions/bar")
* )
* )
*
* @SWG\Definition(
* definition="FooBar",
* discriminator="type",
* required={"type", "name"},
* @SWG\Property(property="type", type="string", enum={"foofoo","barbar"}),
* @SWG\Property(property="name", type="string"),
* )
*
* @SWG\Definition(
* definition="foo",
* allOf={
* @SWG\Schema(ref="#/definitions/FooBar"),
* @SWG\Schema(
* required={"unique_to_foo_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer"),
* @SWG\Property(property="type", type="string", default="foofoo"),
* )
* }
* )
*
* @SWG\Definition(
* definition="bar",
* allOf={
* @SWG\Schema(ref="#/definitions/FooBar"),
* @SWG\Schema(
* required={"unique_to_bar_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer"),
* @SWG\Property(property="type", type="string", default="barbar"),
* )
* }
* )
*/
我正在尝试使用 swagger-php v2.0 记录一个 api 端点,但未正确生成 swagger 文档。
我的用例是我需要从同一端点接受 2 个不同的有效负载,并且某些键只能出现在给定的上下文中。
至于官方文档,可以使用 discriminator
以及 OpenAPI (Swagger) 规范中给出的 allOf
和 this is the example 来实现。
为清楚起见,我将post此处缩小版本
{
"definitions": {
"FooBar": {
"type": "object",
"discriminator": "type",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"name",
"type"
]
},
"foo": {
"allOf": [
{
"$ref": "#/definitions/FooBar"
},
{
"type": "object",
"properties": {
"unique_to_foo_field": {
"type": "string",
}
},
"required": [
"unique_to_foo_field"
]
}
]
},
"bar": {
"allOf": [
{
"$ref": "#/definitions/FooBar"
},
{
"type": "object",
"properties": {
"unique_to_bar_field": {
"type": "string",
}
},
"required": [
"unique_to_bar_field"
]
}
]
}
}
}
我想将其转换为 swagger-php,我想出的如下,但似乎不正确。求教指正,谢谢
/**
* @SWG\Definition(
* definition="model:FooBar",
* type="object",
* discriminator="type",
* required={"type", "name"},
* @SWG\Property(property="type", type="string"),
* @SWG\Property(property="name", type="string"),
* )
*
* @SWG\Definition(
* definition="model:foo",
* allOf={
* @SWG\Schema(ref="#/definitions/model:FooBar"),
* @SWG\Schema(
* required={"unique_to_foo_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer")
* )
* }
* )
*
* @SWG\Definition(
* definition="model:bar",
* allOf={
* @SWG\Schema(ref="#/definitions/model:FooBar"),
* @SWG\Schema(
* required={"unique_to_bar_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer")
* )
* }
* )
*/
好的,在朋友的帮助下我设法想出了一个答案。
为了其他可能遇到同样问题的人的利益,我发布了我自己的答案。
/**
* @SWG\Post(
* @SWG\Parameter(
* name="Create a foo",
* in="body",
* @SWG\Schema(ref="#/definitions/foo")
* ),
* @SWG\Parameter(
* name="create a bar",
* in="body",
* @SWG\Schema(ref="#/definitions/bar")
* )
* )
*
* @SWG\Definition(
* definition="FooBar",
* discriminator="type",
* required={"type", "name"},
* @SWG\Property(property="type", type="string", enum={"foofoo","barbar"}),
* @SWG\Property(property="name", type="string"),
* )
*
* @SWG\Definition(
* definition="foo",
* allOf={
* @SWG\Schema(ref="#/definitions/FooBar"),
* @SWG\Schema(
* required={"unique_to_foo_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer"),
* @SWG\Property(property="type", type="string", default="foofoo"),
* )
* }
* )
*
* @SWG\Definition(
* definition="bar",
* allOf={
* @SWG\Schema(ref="#/definitions/FooBar"),
* @SWG\Schema(
* required={"unique_to_bar_field"},
* type="object",
* @SWG\Property(property="unique_to_foo_field", type="integer"),
* @SWG\Property(property="type", type="string", default="barbar"),
* )
* }
* )
*/