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.

[kiwina]

Hi, just looked at the package and saw that there is a lot taken out of a configuration file like descriptions and other values.
i was trying out vyuldashev/laravel-openapi witch makes heavy usage of goldspecdigital/oooas. Technically extending LaravelJsonApi\Eloquent\Schema to have a few added functions like description or examples would keep it all in one place nice and clear. Just my two cents

[captnCC]

As @glennjacobs mentioned, he has no time to develop his package further, I started a fork under https://github.com/byte-it/openapi-spec-generator
So for anyone who stumbles through here, feel free to test it out. But the status still remains as "under development"!

[Mina-R-Meshriky]

@captnCC can't test as your package only supports php ^8.0
while laravel-json-api supports php ^7.4|^8.0 and I am working on a php 7.4 environment
also can u open the issues I couldn't post that there because the issue tab is not present

[captnCC]

@Mina-R-Meshriky I opened the issues tab! (Didn't know I had to enable it by hand).
For the the 7.4|8.0 topic, open an issue over there and we'll discuss the possibilities!

[robinstraub]

I am using Scribe for documenting my APIs. The package dynamically generate documentation as well as postman collections and OpenAPI spec by interrogating the API and inspecting various code places (e.g. Laravel FormRequest for the request/body parameters).

It doesn't work out of the box for laravel-json-api (as the ResourceRequest and the general flow is a bit different) but it shouldn't be too hard to write a plugin to make it work with laravel json api.

I am currently writing such a scribe plugin locally in my project to much awaited documentation for my team. Considering there is not yet a built-in solution for having documentation with laravel-json-api would relying on an external package and providing a public plugin be an acceptable solution to the lack of documentation tool ?

[lindyhopchris]

Yeah I think if you're writing something, then publishing it as a package people could use would be a great help. I'm limited on open source time, and with the amount of issues building up I'm unlikely to get to documentation any time soon. So other people dev'ing packages is a great help!

[isaackearl]

I'm just here to pile on and say some sort of recommended approach or built in behavior would be an incredible addition to this package. I wouldn't mind it being through Scribe. Did you ever get a good plugin working @robinstraub ?

[isaackearl]

I'd be willing to pay a bounty on this if someone has fleshed out a scribe plugin, or some other way to generate nice docs. Shoot me an email or message me here if someone wants to chat about it.

[zlodes]

There is a cool openapi-package: https://github.com/vyuldashev/laravel-openapi

I beleive that it will be able to build OpenAPI documentation using this package and auto-generated schemas.
I'm gonna try it a bit later.

[dog5tar]

Did anyone ended up with a solution they like? After reading the thread I can see there were different approaches being tested but does not seem we have a final (best way) for it.

[plunkettscott]

Hey @lindyhopchris,

I'm going to work on tackling this, I need more in-depth docs, and I think given the other options here I have a pretty good foundation of how this can work. Would you be open to adding methods to filters, schema fields, and other parts of the package to enable providing additional information for documentation (ex: description)? Or maybe even making them macroable?

Right now I am extending the package classes, but I worry that without first-party support its possible that could break in the future if you add a new method that conflicts. If you think this is the right direction, I'm happy to continue down this path. It's worked well so far.

---

Edit: I've also considered a documentation method directly on Schema classes. I would like to avoid requiring all the fields to be duplicated in order to describe them. Code duplication is something you set out to solve in this version of the JSON:API package, so I'd really hate to re-introduce duplication.

[lindyhopchris]

@plunkettscott that would be great if you could work on this - basically, I've got plenty of other things to do on this package and OpenAPI is a feature I'd like but for my production projects I don't need it at the moment - which is why I haven't been prioritising it.

I'm happy for you to propose additions to the fields etc to make documentation work. However, I'd prefer not to add too many methods to the fields that are specific to documentation - because calling those methods in the schema will incur a cost everytime the schema is created as part of a request, which has nothing to do with documentation and needs to be as performant as possible. I'd be interested to hear your thoughts about how this could potentially be implemented without adding lots of documentation specific methods to the fields etc.

Textual information for documentation also needs to be translatable - so we need to work out how to do that as part of the implementation. Potentially there might be some sort of approach where textual information could go into translation files rather than being added to fields in the schema. We could have some sort of Artisan command that generates the files that you need to add the textual information to based on analysing the schema.

They are just my thoughts. The priority from my perspective is not to impact the performance of the implementation just to add documentation - if we can find an approach that does that then I'm defintely interested in adding it as first-class support within this package.

[gilbitron]

@robinstraub Did you get anywhere with the Scribe plugin for this?

[nelson6e65]

I'm using @bbrala's swisnl/openapi-spec-generator to generate the documentation and (after moving the resulting .json to a public storage) I display it with stoplightio/elements.

It is relatively easy to integrate stoplightio/elements with Web components in your current Inertia Vue app or in a simple separated Blade app with some adjustments in fetch headers, by even using the Sanctum SPA auth for the API try-it-out calls.

swisnl/openapi-spec-generator is lack of some features (like include query parameter), but I think that with some help it can be a great generic tool to generate JSON:API docs.

[lindyhopchris]

Hadn't realised that openapi-spec-generator package had been created.

[nelson6e65]

Hadn't realised that openapi-spec-generator package had been created.

@lindyhopchris yes, there are a few folks. I think the one I mentioned is the more stable.

[ben221199]

The libraries of @swisnl are very nice. It's also a Dutch company. 🙂 In my code I use their swisnl/json-api-client a lot.

(By the way, it is a fork of a fork, so they are possibly not the original creators.)