search

cloudcreativity / laravel-json-api

JSON API (jsonapi.org) package for Laravel applications.
http://laravel-json-api.readthedocs.io/en/latest/
Apache License 2.0
780 stars 109 forks source link

Automatically generate OpenAPI compliant documentation #489

Open daryledesilva opened 4 years ago

daryledesilva commented 4 years ago

Hi, do you have any plans on adding a new feature that adds support for generating OpenAPI compliant documentation out of the api configuration? It would be really nice to have!

lindyhopchris commented 4 years ago

Hi! Yes this is something I'd love the package to do at some point... but time is currently my enemy! I think the refactoring mentioned in #411 needs to be done first, because I don't think it would be sensible attempting to do the OpenAPI stuff now when I'm about to refactor the internals of the package.

daryledesilva commented 4 years ago

I just saw #411 yes it makes sense for that to be done first. okay thank you for the response, and maintaining the project! awesome job 😁

lironesamoun commented 4 years ago

Hi ! Any updates for generating a documentation for the API ? =D

lindyhopchris commented 4 years ago

No updates yet, it's dependent on implementing the new version of the package. I'm planning a sprint on that probably in November as I'm expecting to have a week or so between paid work.

lindyhopchris commented 3 years ago

The new package is now available - laravel-json-api/laravel see https://laraveljsonapi.io

I'd love to add Open API documentation generation.... but time is still a problem for me. If there are any volunteers who would like to step forward to take this on as a project, then that would be superb - just let me know.

happyDemon commented 3 years ago

I'm willing to have a go at this over the weekend

cruzvale33 commented 1 year ago

Some updates for the API documentation generation?

lindyhopchris commented 1 year ago

It won't be added to this package, as this package (cloudcreativity/laravel-json-api) is legacy. Still an intent to add it to the new package (laravel-json-api/laravel) but realistically someone needs to step up to contribute it as it's difficult for me to prioritise at the moment.

nelson6e65 commented 1 year ago

There is a WIP package working on a tool for laravel-json-api/laravel: https://github.com/swisnl/openapi-spec-generator

genyded commented 1 year ago

This can be accomplished/addressed with https://scribe.knuckles.wtf/laravel/documenting/custom-endpoints. It's not quick and easy but then none of the packages that help with API docs using docblocks and such are.

This one however allows you to create create YAML files (they can Camel files) and it will respect (not overwrite) and integrate those during doc generation/regeneration. It supports OPENAPI generation/creation and even has a nice JS based 'Try It' feature should you choose to enable it.

Those YAML files can be used to pretty easily document things like JSON:API endpoints or anything that does not follow the standard Laravel conventions for route/controllers/requests, and so on that most of the doc generators try to parse when generating docs.

Basically instead of the typical docblocks, you create one of these yaml files for each JSON:API 'group' of endpoints you want to document along with the details for each endpoint in that group. Then upon doc generation/regeneration, those get parsed instead of routes and/or docblocks to provide the docs and examples for the JSON:API endpoints. You can also use the other methods (routes/docblocks) for non-json:api endpoints in conjunction with your custom yaml files (in fact doc generation creates or appends to them to propagate them into the docs when you generate anyway).

I/we are not associated with Laravel Scribe at all and this is not a plug for it. It just happens to be what we landed on after a ton of trial and error trying to solve the exact issue of API documentation for the JSON:API or any other non-typical Laravel integrations.

Once you get familiar with the Scribe package and the foundation set up with everything the way you like it, we actually find much faster and easier then docblocks anyway. You just have to decide on your initial groups and which endpoints you want where and then add/append to them as you go. There is a YAML file for each 'group'.

genyded commented 1 year ago

Oh and I forgot to mention another option that may work better for some teams or people who hate YAML. If you happen to be using the tests that Laravel JSON:API provides and have tests for all the endpoints that you want to document, there is a Scribe TDD plugin https://github.com/ajcastro/scribe-tdd that can be added to generate the docs (and OPENAPI spec) from the tests instead of the code.