Generating an OpenAPI spec

[brayniverse]

Hello 👋,

I have been manually creating a JSON:API implementation and while I think we've been doing a good job there has been mistakes along the way. When looking at this package I reckon we wouldn't have made as many if we were using json-api-server. I have been experimenting with the package and it seems really good.

All this is to say, I'm still new to the package and forgive me if this has already been asked. As far as I could tell, there hasn't been a discussion on it yet.

Is it possible to generate an OpenAPI spec file from the schema you define as part of json-api-server? It seems like all the information to generate one is available. If it is not currently possible, would you consider including it as part of the core package if I were to help implement it?

Thank you,

Chris

[tobyzerner]

Hey Chris, thank you for the kind words 😊

You're right that this hasn't been talked about before, but it's always been in the back of my mind as something that would be possible and desirable.

In a couple months I'm starting a new job that will allow me to invest a lot more time into this package, and I'd love to look at it then. In the meantime, any start you can make would be great!

[brayniverse]

@tobyzerner congratulations on the new job. I'll see what I can do.

[tobyzerner]

With the release of v1.0.0-alpha.1, which adds support for typed attributes, consider work on OpenAPI definition generation well underway :)

[bertramakers]

Hi @tobyzerner, is there any news regarding the OpenAPI spec support?

[tobyzerner]

Hi @bertramakers, work is in progress (but incomplete) on the openapi branch. Feel free to try it out and let me know what you think!

use Tobyz\JsonApiServer\OpenApi\OpenApiGenerator;

$api = new JsonApi();

// $api->resource(...) etc

$generator = new OpenApiGenerator();

print_r($generator->generate($api)); // or encode as json, yaml

[bertramakers]

Thanks, I'll try it out soon!

~One small suggestion I already have would be to put the name of the collection in the summary of the operation instead of the tags~: https://github.com/tobyzerner/json-api-server/compare/main...openapi#diff-03e5541a3e5fe9ec77d2c71f17861fe6c28554322af2fd5cd0f6dd5b2daa3fe7R188

~See definition of summary in operation objects here: https://swagger.io/specification/#operation-object~

Edit: Disregard this, it makes sense to put $collection->name() in tags because it's usually the type of the resource and not the name of the operation. It would be nice to be able to set a name/summary on the endpoint though but that's nice to have.