search

cebe / php-openapi

Read and write OpenAPI yaml/json files and make the content accessible in PHP objects.
MIT License
466 stars 88 forks source link

Inconsistent typehints for Reader #23

Closed scaytrase closed 5 years ago

scaytrase commented 5 years ago

https://github.com/cebe/php-openapi/blob/5e68074e2b82a0c0703753eeac3662a8a39e1c5d/src/Reader.php#L30

all reader method declare returning SpecObjectInterface while phpdocs say that it should be the OpenApi object instance. Also phpdocs are redundand, since SpecObjectInterface|OpenApi equals to SpecObjectInterface as OpenApi implements SpecObjectInterface.

It looks like having OpenApi as return typehint signature is more straightforward, as it would agree with return phpdoc and comment and the expectations of end user

cebe commented 5 years ago

The type of the returned object depends on the value of $baseType argument, which defaults to OpenApi, but it can be any instance of SpecObjectInterface. So the correct annotation would be just SpecObjectInterface, I added OpenApi because it is the most common type returned and will allow IDEs to provide better autocompletion.

cebe commented 5 years ago

I added an additional sentence to the PHPdoc, is it better now?

scaytrase commented 5 years ago

It's a bit more clear now, yes. I got the idea, thank you

I hope one day we can create `Reader::fromJson($json): OpenApi