Using discriminator together with allOf

Question

I'm trying document an api endpoint using swagger-php v2.0 but the swagger documentation is not correctly generated.

My usecase is that I need to accept 2 different payloads from the same endpoint and the some keys can only be present in the given context.

As for the official documentation it can be achieved using discriminator along with allOf and this is the example given in OpenAPI (Swagger) Specification.

For clarity I'll post a shrunken down version here

{
    "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"
            ]
            }
        ]
        }
    }
}

And I want to convert this for swagger-php and the one I came up with is as follows, but seems it's not correct. I seek advice to correct it, thanks.

/**
* @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

Okay, I managed to come up with an answer with a help of a friend.

And for the benefit of others who might stumble upon the same issue, I'm posting my own answer for this.

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