Question

我正在尝试使用swagger-php v2.0编写api端点文档，但是未正确生成swagger文档。

我的用例是，我需要从同一端点接受2个不同的有效负载，并且某些键只能在给定的上下文中出现。

对于官方文档，可以使用discriminator以及OpenAPI（Swagger）规范中提供的allOf和this is the example来实现。

为清楚起见，我将在此处发布缩小版本

{
    "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")
*          )
*      }
* )
*/

Answer 1

好的，我设法在朋友的帮助下给出了答案。

为了其他可能会偶然发现同一问题的人的利益，我为此发布了自己的答案。

/**
* @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"),
*          )
*      }
* )
*/

与allOf一起使用鉴别符

1 个答案: