Automatically generate OpenAPI documentation

[lindyhopchris]

This has been on the wish-list for some time, the latest issue in the legacy package is this:
cloudcreativity/laravel-json-api#489

Hopefully this should now be easier because of the new Nova-style schemas.

My main problem is time to do it - if there are any contributors who want to work on it as a project, let me know.

[martianatwork]

Hey, leaving this gist here if anyone wants to achieve this functionality,

https://gist.github.com/martianatwork/7fbb543fc9565cc9bfcf04c52e9ed84b

I will create a package when i get more time.

[glennjacobs]

OpenAPI v3 spec generation would be amazing. Especially if it was generated with ReDoc in mind enabling you to have x-tagGroups etc.

Just started my project using this package, but once further down the line I'd like to see what could be done.

[lindyhopchris]

Yeah, it should totally be possible to do. I just need some collaborators to step forward to have a go at implementing... the reality is there's too many issues for me to handle by myself, so getting onto OpenAPI docs generation is going to take a me a long time if I don't have any help.

(Just putting this here to be clear what's blocking getting this done.)

[glennjacobs]

No problem. If there's no progress in a couple of months time by anyone else, I'll happily have a go.

[glennjacobs]

I'm going to give this a go and try convert to a package. Managed to get the example Gist to run and will start to improve the spec to produce nice API docs via ReDoc. Once I have an initial package running I'll share a link to the repo here.

[lindyhopchris]

@glennjacobs sounds good.

For info, the thing that isn't right about the Gist is it is producing the docs in the controller action. The docs will be static, so it would be a lot better if they were generated using an Artisan command and stored for serving from a controller action. Then doc generation because an Artisan command that you run in your deployment pipeline.

[glennjacobs]

Yep, defo be generating a static file via a commmand! 👍🏻

Got lots of good ideas for it.

[glennjacobs]

The one thing I'm still unsure about is where to put additional information such as method descriptions. No obvious place at the mo and I don't think a config is the correct place.

[Wizofgoz]

@glennjacobs if your package is limited to PHP 8, I'd say attributes might be a good way of doing it. Otherwise, maybe reflection to get doc blocks.

[glennjacobs]

@glennjacobs if your package is limited to PHP 8, I'd say attributes might be a good way of doing it. Otherwise, maybe reflection to get doc blocks.

Yeah, I thought about those options. I need to have a read up on how I can programmatically access them.

[glennjacobs]

I've made a reasonable start, you can find the repo here https://github.com/neondigital/openapi-spec-generator

The generator code needs a LOT of tidying up, but it appears to work and I have a test suite working and ready to add to.

My next steps are to tidy up the code and start moving through all the different relationships etc.

[lindyhopchris]

@glennjacobs yeah think you'll need me to review it too, but I'd probably prefer to do that when it's tidied up!

[glennjacobs]

Oh yes! It's certainly not "done" yet.