10 - Generate API Docs | Laravel Daily

One of the most important but overlooked things is to document your API for future clients, whether they would come from a JS front-end, or a mobile app. Things like:

Endpoints
Parameters
Auth mechanism
Example responses

Luckily, there are a few Laravel packages that allow you to generate such docs automatically. You configure things you need, by modifying the config file and adding some comments to your routes/controllers, then you run an Artisan command, and it saves the static HTML files to a public folder on your server. As a result, you can just send the link to it, to your API consumers.

My personal favorite package for this is called Scribe, and we will use exactly that one.

The Full Lesson is Only for Premium Members

Want to access all of our courses? (36 h 00 min)

You also get:

61 courses

Premium tutorials

Access to repositories

Private Discord

Get Premium for $129/year or $29/month

Already a member? Login here

rafa1944 3 years ago

Thanks Povilas, very good resource!! Let's go for the second part? like Front-ent integration or payment? haha keep the good job!

👍 1

Gavin Kimpson 3 years ago

I second the frontend integration!

👍 1

Povilas Korop 3 years ago

Front-end integration tutorials for Vue and React are already in progress, for February :)

👍 1

🥳 1

andywong31 3 years ago

im excited for the front-end integration! thanks Povilas!

👍 1

Gavin Kimpson 3 years ago

I will try to be as active as Andy in the comments too :) Look forward to the frontend integration - i'm doing a frontend integration in Vue now so it will be good to compare my 'attempt' to yours (your frontend will be a 100x better I am sure lol)

👍 1

Povilas Korop 3 years ago

@Gavin I'm not a front-ender at all, so I wouldn't fully count on my implementation being better :)

Gabor Gazdag 2 years ago

Thank you! Very nice tutorial!

Gavin Kimpson 3 years ago

Still debugging this - however when I run the php artisan scribe:generate command I get the following error, anyone else had the same problem? P.S I added the @group <Controller> code to each controller

/**
 * @group Auth
 */

Output from VS Code

 ErrorException
 
Undefined array key 1
 
at vendor/knuckleswtf/scribe/src/GroupedEndpoints/GroupedEndpointsFromApp.php:223
  219▕
  220▕     private function isValidRoute(array $routeControllerAndMethod = null): bool
  221▕     {
  222▕         if (is_array($routeControllerAndMethod)) {
➜ 223▕             [$classOrObject, $method] = $routeControllerAndMethod;
  224▕             if (u::isInvokableObject($classOrObject)) {
  225▕                 return true;
  226▕             }
  227▕             $routeControllerAndMethod = $classOrObject . '@' . $method;
 
    +18 vendor frames
19  artisan:35
    Illuminate\Foundation\Console\Kernel::handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))

Gavin Kimpson 3 years ago

Weirdly - I cloned your copy of the Laravel car parking app from github and ran the scribe command and it works fine... so there is something weird with mine i'll try to dig more into it over the weekend

Povilas Korop 3 years ago

Yeah, again, I can't debug what I haven't encountered myself. Let us all know if you find the difference. That's, by the way, the downside of all those auto-generating tools: you need to be precisely careful with how your docblocks are written.

👍 1

Gavin Kimpson 3 years ago

I'm not so fussed with the error above as I can always use your original repo, but I have gained a lot of insight especially with the phpunit tests! Thanks I really enjoyed this one a lot :)

Povilas Korop 3 years ago

Well, I didn't plan the hightlight of this course to be the TESTING lesson, added it as a bonus mostly, but... whatever works! :)

👍 2

Ali Al Qahtani 3 years ago

Very good course

Povilas Korop 3 years ago

Thanks Ali!

Elmar Cabbarlı 3 years ago

Thank you for the course. I love writing clean code and the course reflects that. So, i have a question, I want to create laravel api and apply authorization. i discovered sanctum from this course and confused for authorization. I used to spatie laravel permission package for authorization. But there is a similar option in sanctum which is abilities. So i want to ask that or please give me advice for this, what should i use for authorization? or what do u use for authorization?

Povilas Korop 3 years ago

Personally, I've never used Sanctum abilities, only spatie/laravel-permission. I'm not sure if those abilities would work the same, I'm just used to the package that I've been using for years now.

abphaiboon 3 years ago

Awesome course :) Thank you.

haritjahjo 3 years ago

Thank you Povilas.

Ngozi Stephen Onyemauche 3 years ago

Thank you Povilas, awesome course

👍 1

porrapat 3 years ago

Thank you, this is good course!

porrapat 3 years ago

Are you forget @group Auth in LogoutController?

Povilas Korop 3 years ago

Yes, good point, forgot about that, but now too much work to change and re-do the screenshots :)

mohannad banattaf 2 years ago

Hello and thanks for the course. I have a question altho regarding "response_calls", did it change name because i cant find it.

👍 1

Jim Adamek 2 years ago

Thanks for recommendation for Scribe to produce API documents. I was looking for a more automated solution. You do a great job of pointing us in the right direction with your examples and how to...

Generate API Docs

The Full Lesson is Only for Premium Members

We'd Love Your Feedback

Thank You!