allOf/anyOf/etc. in PHP Attributes

[BusterNeece]

Hey all! I've scoured the documentation and I really can't find out the recommended way of implementing something like this:

<?php
/**
 * @OA\Parameter(
 *     parameter="station_id_required",
 *     name="station_id",
 *     description="The station ID",
 *     example=1,
 *     in="path",
 *     required=true,
 *     @OA\Schema(
 *         anyOf={@OA\Schema(type="integer", format="int64"), @OA\Schema(type="string", format="string")}
 *     )
 * )

into PHP attributes.

The closest I've been able to come so far is:

<?php
#[OA\Parameter(
        name: "station_id_required",
        in: "path",
        required: true,
        schema: new OA\Schema(),
        // new OA\Schema(type: "integer", format: "int64"),
        // new OA\Schema(type: "string", format: "string"),
]

But I'm not sure how to express the "anyOf" value for the parameter using the attributes. Nothing I'm trying is validating properly. Any ideas?

[DerManoMann]

All the properties are still the same. In your attribute you've used name for "station_id_required" not parameter. Could be that.

[BusterNeece]

@DerManoMann Turns out that's not exactly true, as things are moved around when using annotations.

For example, the name of a parameter is now being used to determine its ref path, not the parameter value. In fact, if you even try to specify a parameter value, it throws:

Fatal error: Uncaught Error: Unknown named parameter $parameter

Also, I figured out how to do the "anyOf" thing, and it's a bit more complicated than I expected:

<?php
#[
OA\Parameter(
        name: "station_id_required",
        in: "path",
        required: true,
        schema: new OA\Schema(
            properties: [
                'anyOf' => [
                    new OA\Schema(type: "integer", format: "int64"),
                    new OA\Schema(type: "string", format: "string")
                ]
            ]
        ),
    )
]

[DerManoMann]

Sounds like a bug to me :)
Any chance to get a small, complete snippet for both annotations / attributes that should result in the same YAML? That would help me a lot.

[DerManoMann]

@SlvrEagle23 Could you please try the PR and see if that fixes things?

[BusterNeece]

@DerManoMann Testing with the latest dev-master and discovering that now there is no official way to specify anyof on a Schema, because the previous properties was removed, but anyof/allof/etc wasn't added.

How would I accomplish what I was trying to do above? Basically, the given parameter can be AnyOf a string or an integer.

[BusterNeece]

As frustrating as it is, basically it appears that every single possible parameter that could be passed to a property has to be specified in its constructor, and just having it as a public property isn't sufficient for IDEs not to have a fit. anyOf, allOf, etc. are in the Schema parent, but not in the constructor of the Schema attribute.

[DerManoMann]

Ah, this might be a merge issue. Certainly those should be there...

[DerManoMann]

Pretty much all named parameters should now be available

[BusterNeece]

@DerManoMann Playing with it locally and it's working wonderfully, basically as a drop-in replacement for the annotations at this point. Thank you for your hard work on this, it really makes our code look great when everything's in the attributes!

[DerManoMann]

Thanks. Glad you like it.

[BusterNeece]

@DerManoMann One thing I noticed: Response is missing its ref property in the attribute constructor.

[BusterNeece]

@DerManoMann Also noticing ref is missing from Parameter...it may merit another sweep to make sure there aren't any missing properties.

[BusterNeece]

@DerManoMann I'm back on the dev-master branch to play with the latest changes and with Response, I'm noticing that currently it's not accepting just a $ref value the way that parameters do, and it's throwing an error about missing a response/description parameter even when a ref is present.

[DerManoMann]

@DerManoMann I'm back on the dev-master branch to play with the latest changes and with Response, I'm noticing that currently it's not accepting just a $ref value the way that parameters do, and it's throwing an error about missing a response/description parameter even when a ref is present.

I think that might be correct; at least the response parameter is required as it is the key (status code or default). These validation checks should be the same irrespective of whether you are using annotations or attributes.

[BusterNeece]

@DerManoMann Looking through the spec document, it would appear all you need is the name and the $ref and everything else can be defined in the ref: https://swagger.io/docs/specification/describing-responses/

[DerManoMann]

The name? How would that look in yaml?
Also, perhaps you could open a new issue for that?

[BusterNeece]

@DerManoMann Sorry, by the response's "name" I mean the response value. I can make a new issue about this tomorrow if need be, sure.