Add v3.1 schema and validation based on it

[WyriHaximus]

No description provided.

[mariosimao]

Hi @cebe, any plans regarding this PR? Is there something missing that I could help?

[WyriHaximus]

Hey @cebe I hate to ping, but ping?

[Mark-H]

Had a quick play with this, validate seems to do the trick validating a 3.1 schema. Compared it with Spectral's validation for a spec written in the Stoplight editor.

With a valid schema:

➜  vendor/bin/php-openapi validate api-schema/openapi.yaml
The supplied API Description validates against the OpenAPI v3.1 schema.
➜  spectral lint api-schema/openapi.yaml
No results with a severity of 'error' or higher found!

And when breaking some random stuff in the schema to see it catches the issues it's also flagging what I'd expect:

➜  vendor/bin/php-openapi validate api-schema/openapi.yaml
Errors found while reading the API description from api-schema/openapi.yaml:
- [/info] Info is missing required property: version
- [/paths/~1recipes/get/parameters/1] Parameter is missing required property: name
- [/paths/~1recipes/get/parameters/1] Parameter is missing required property: in
OpenAPI v3.1 schema violations:
- [info.version] The property version is required
➜  spectral lint api-schema/openapi.yaml

/path/to/api-schema/openapi.yaml
   1:1   warning  oas3-api-servers  OpenAPI "servers" must be present and non-empty array.
   2:6     error  oas3-schema       "info" property must have required property "version".  info
 115:11    error  oas3-schema       "1" property must have required property "in".          paths./recipes.get.parameters[1]

✖ 3 problems (2 errors, 1 warning, 0 infos, 0 hints)

convert is also working as expected on the schema and I can also walk through the schema with the PHP API, e.g.:

<?php
require __DIR__ . "/vendor/autoload.php";

$openapi = \cebe\openapi\Reader::readFromYamlFile(realpath(__DIR__ . '/api-schema/openapi.yaml'));
$recipe = $openapi->paths['/recipes/{recipeId}'];
var_dump($recipe->get->responses->getResponse(200)->content['application/json']->schema->properties);

I'm not too well-versed in the openapi 3.0/3.1 spec differences to say if this might need more work to complete the 3.1 integration but so far this seems to be working well.

[Jean85]

Other differences that we need to implement to fully support 3.1 are listed in #101

[WyriHaximus]

Got a bunch of that ready to be PRed once this PR is in.

[marcelthole]

@cebe you provide a make file script schemas/openapi-v3.0.json and schemas/openapi-v3.0.yaml.
Both scripts use the composer virtual dependency oai/openapi-specification which also needs to be updated.

This Pull Request didn't update these files. Should it be removed, or would you prefer an update of the package and make file?

[WyriHaximus]

@marcelthole Can look at that if desired, don't recall how I got the 3.1 files but probably just downloaded them.

[cebe]

did that in #128

[cebe]

@WyriHaximus thanks for starting this, I made a slightly different implementation in #128, which replaces this PR but includes most of your changes.

[WyriHaximus]

@cebe Sweet!