Published 8 months ago by malhayek
I have an API that is written on a top of Laravel 5.5. I need to write some sort of documentation for it so people know how to use it.
Is there is a best practice document that I can use as a guide to help me writing the document?
Is there an API example of a Laravel project with document that I can look at? Or is there a standard documentation template that the community use with Laravel based APIs?
Swagger is great, no doubt. However, it is sometimes a little too opinionated, or over-the-top.
To add to your options, when I've wanted code documentation that was a little less demanding (read: simpler for project needs), I have used these, for your consideration:
Both of which serve slightly different purposes, but are quite effective.
I created a small dummy api documentation page which can be found here https://jsfiddle.net/DTcHh/41786/
Can you please share with me your thought on this style? Is it missing anything or is it complete? Does it do a good job explaining everything?
That looks quite nice - however it's very "programmer-y". If I were a programmer taking over this project much of this information could be inferred from
artisan route:list, except prettier in this format.
Perhaps some information I'd find useful would be:
Stuff like that?
@burlresearch thank you for your feedback again.
artisan route:list will give you most of that info if your the developer but an outside person who is looking to integrate their system won't have access to that.
Regarding our 4 bullet, In a typical Laravel based API, how would one establish connection? I mean how would one trying to interact with the API generate a token? Does the token change ofter like the csrf token or is it like a session id?
For sure - this documentation will be useful to outside programmers. So this will be good documentation. But I would be an "outside programmer" if I used this API - so I'd want to know:
401-Unauthorized: then how can I become authorized?
These are just ideas - you know who your clients will be. Try to put yourself in their shoes (not knowing anything about your API), and imagine what questions you could answer to make their job, of using your API, as easy as possible.