Generate API documentation

[NiCr42]

Is there any way of generating an end user API like swagger.io (or any other api documentation generator) ?

Thanks.

[lindyhopchris]

Hi! No not at the moment. It's not something I think I'd have time to get to based on everything else that needs to be done. I'd be interested in hearing your thoughts as to how it could be done if you had ideas?

[moneal]

You can use https://github.com/DarkaOnLine/L5-Swagger to generate documentation but it requires manually writing docblock comments for each method. I use Google Endpoints as a frontend for my API and it requires a swagger config to define requests. Its a bit of extra work but is nice. I would love for this to be autogenerated.

[chriscalip]

+1

[chriscalip]

How about a transition way of providing a swagger.json for https://github.com/cloudcreativity/demo-laravel-json-api

Comment withdrawn because swagger and jsonapi seems to be a pita to integrate.

Reference:
swagger-api/swagger-core#1849
Swagger customization for JSON API specification
Consensus: Swagger currently does not handle JSON API.

[igorsantos07]

This is sad. An API without documentation is like a book in a foreign language: the author know what was written, but readers can't get to the message without jumping to the dictionary very often.

It's also sad to see Swagger is hard to integrate with JSON-API, as both are beautiful tools for the API-land.

Another suggestions to check would be API Blueprint.

Would be nice if, at least, there was something like an OPTIONS endpoint that would spit out the available verbs, fields and other options each resource would respond to...

[lindyhopchris]

@igorsantos07 I'd happily take PRs if this is something you're able to help with. Unfortunately I haven't had time to get to this yet.

[igorsantos07]

I would love to be able to help on this, as I'm really sad with the state of REST APIs on PHP (been a past contributor to Restler), but unfortunately the project I'm in is quite time sensitive and I probably wouldn't have time to bring something back here... Will probably just use a different package / simpler API, or write docs by hand :(

[lindyhopchris]

That's ok - I understand. It's exactly the same for me, and I can only get to adding things into this package when there's time between work.

[johannesschobel]

Maybe this project here ( https://github.com/saleem-hadad/larecipe ) may be a viable strategy? Althoug it does not allow for automated doc generation from docblocks, it uses markdown to create quite beautiful docs..

However, if using this package would be an option, i would vote for "not including" this package by default but rather provide assistance in "how to include" it (e.g., write documentation on how to integrate both packages)

[lksnmnn]

We've built a Laravel package which generates API docs in JSON, HMTL and Swagger by reading from the Adapter/Schema/Validator classes. It is currently closed source and only works with laravel-json-api v0.26

I may find the time to update and release it.

[lindyhopchris]

@lksnmnn that sounds great! definitely let me know if you decide to open source it and if i can help in any way.

[daedeloth]

We've built a Laravel package which generates API docs in JSON, HMTL and Swagger by reading from the Adapter/Schema/Validator classes. It is currently closed source and only works with laravel-json-api v0.26

I may find the time to update and release it.

I'm about to do the same thing so if you are willing to release something, I'd love to have a look :-)

[lindyhopchris]

Also, if you see the discussion on #411 - we'd love to add this capability for v2 of this package. So if anyone here is working on that kind of thing, it'd be great to work towards adding it to this package so that people get the capability out of the box!

[crabmusket]

Has any thought been put towards using an existing specification (e.g. in OpenAPI format) to generate Laravel code using this package? I've just been reading through Phil Sturgeon's books on API design and he advocates for doing a spec first using e.g. OpenAPI, from which you can generate a bunch of useful things - clients, documentation, tests, mock servers, etc. I guess if the first step is writing PHP then you get an OpenAPI document out of it at the end, that's not too different, but I thought I'd ask!

EDIT: more on the subject. https://apisyouwonthate.com/blog/api-design-first-vs-code-first