Polymorphics

[hotmeteor]

Adds support and tests for oneOf, anyOf, and allOf polymorphics.

Some notes:

• In order to use oneOf you need to either defined required properties or set additionalProperties: false. The oneOf documentation doesn't have this, but this is in error.
  • You can find more details in this thread here: "value property should match exactly one schema in oneOf" message with right example stoplightio/spectral#1482 (comment)
• allOf only seems to work with anyOf, not oneOf. Not sure if this a limitation of the library or OpenAPI, but there is an open ticket about this on cebe/php-openapi: allOf is not properly merged cebe/php-openapi#31 (comment)

[bilfeldt]

@hotmeteor This PR is much appreciated. I have tested this branch on the specs I have found a problem when declaring a property within a allOf as nullable:

Example below causes an issue with the id when this is null.

 ================================================== 
  Request body did not match provided JSON schema.  
 ================================================== 
  ⨯ The data should match all schemas     
  ⨯ The properties must match schema: id          
  ⨯ The data (null) must match the type: string   

The specs have a response defined by:

                "responses": {
                    "401": {
                        "$ref": "#/components/responses/401"
                    }
                }

Which is defined like

        "responses": {
            "401": {
                "description": "Unauthenticated request. Please provide correct authentication.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/DetailedError"
                        }
                    }
                }
            }
        }

And this is the components for

            "Error": {
                "description": "Error response",
                "required": [
                    "message"
                ],
                "properties": {
                    "message": {
                        "description": "Description of the message",
                        "type": "string",
                        "example": "Description of the error will be inserted here."
                    }
                },
                "type": "object"
            },
            "DetailedError": {
                "description": "Detailed Error response",
                "required": [
                    "message",
                    "code"
                ],
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Error"
                    },
                    {
                        "properties": {
                            "id": {
                                "description": "Unique ID of the error",
                                "type": "string",
                                "example": "",
                                "nullable": true
                            },
                            "code": {
                                "description": "Code describing the type of error",
                                "type": "string",
                                "example": "ValidationException"
                            },
                            "errors": {
                                "description": "Object with keys corresponding to the fields and each key containing an array of errors. OpenAPI does not allow for dynamic keys until version 3.1 is released",
                                "type": "object"
                            },
                            "links": {
                                "description": "Object with dynamic keys, each with a URL string value. Dynamic keys are not part of OpenAPI until version 3.1 is released",
                                "type": "object"
                            }
                        },
                        "type": "object"
                    }
                ]
            }

And this is the actual response:

{
    "links":{
        "about":"http:\/\/localhost\/docs\/errors\/UnauthenticatedException",
        "status":"http:\/\/localhost\/status"
    },
    "id":null,
    "code":"UnauthenticatedException",
    "message":"Unauthenticated.",
    "errors":{
        "header.Authorization":[
            "Provide a Bearer Token as Authorization header"
        ]
    }
}

Testing

Does this package have some neat way of manually validating a request and/or a request+response agains a specification?

I mean imagine I could test using something like:

Spectator::using('api-docs.json')->validate($request, $response); // Would throw some sort of exception if it fails I would guess

And perhaps the ability to only check the request:

Spectator::using('api-docs.json')->validate($request); 

[hotmeteor]

@bilfeldt What version of OpenAPI are you using: 3.0 or 3.1?

Also, that's an awesome idea. It's not currently available but I think it should be doable, I'll see if I can add it.

[jarrodparkes]

@hotmeteor I added some tests to cover equivalent polymorphic cases on the response-side. The main change was ensuring the json_decode call was also performed for the oneOf and anyOf cases for the response's body. I also took a stab at adding some more error feedback for messages that were purely one-to-one mappings of errors generated by the opis/json-schema validator.