How to Quickly Generate Laravel API Documentation

how to quickly generate api de plantation for your level API for example if you work with front-end er with mobile developer or with anyone who wants to use the API how do you provide the documentation and there is a laravel package that helps you to do that very quickly and I will demo it for you now I have a small project created by my teammate Marius really simple a shop catalog homepage and I will shoot a separate video on this one how it works with UJS but for now let's create a documentation for its API so there are only two endpoints two pages list of products and list of categories and if you can see in the network tab of the browser there is a category API with this result and there's a products API with this result and in laravel code we have two controllers for API product controller and category controller and our dog block blocks that will help us to generate the documentation but the controllers are really simple just index function for all the categories and maybe some more logic in products because they have pagination so on the example of that simple project I will show you the basics how to generate documentation for a bigger project of course it's more complicated but you would know the principles for that we would use a package by Marcel Basquiat called laravel API Talk generator it's really old like four years ago some files and two and a half thousand stars so very good for simple D connotations so here's how it works after you install and configure that you just run command artist an API Talk generate like this and it generates public dogs index.html file that you can view with the browser so slash dogs becomes your official API now how does that package know what to generate here what is the syntax there is a specific syntax so in every method or a fabric controller let's start with the categories you need to provide some information so first before the class you can assign a group so ad group becomes this thing this menu item on the Left parent menu item is a group front page this API is for frontpage is a group title here group description and that for every method you can describe every method and it becomes submenu item here so let's start with the categories fetch all categories and fetch categories are here so in dog block first line is the title second line is a description subtitle then you can provide a lot more things like authentication query parameters and all of that but probably what is most useful to the front-end err or to mobile application developer is the response the example of what they can expect and this is exactly how it looks formatted response so at response and you just give any example response and from here front enter would definitely understand that this is the URL this is the content type and the parameters and this is what they can get this can be dummy data some fakir data some whatever but at least it shows the structure that is the most important thing and for product list is little more complicated because it has pagination so we have query parameters here so if you go to the page and click the category there are URL parameters category 1 and page 1 and these are exactly here for every ad query pram name of the parameter then space description and then example value and this becomes this table so when you specify query parameter list you have this table and example five and example two it goes to here to example request so also then front enter is familiar with what parameters to pass and what are potential values and then response is pretty same thing just in this case response is more complicated with pagination with next page previous page and all of that so in our case when we're working with a bi project and want to provide that to the front-end er we make the changes in the API then regenerate the documentation push that to the repository and then that HTML page gets updated final thing I want to show you how to generate that response probably doesn't come manually so to get that response you can actually run that API call in browser so let's go here we have actually run that products or actually categories so categories and this is the result in the browser in chrome its network then you choose the network all and then go response copy that of course it's not formatted it's one line but then there is the online tool like JSON format org I like this one so I just paste here and then click format beautify and that's it it gives me the full structure more readable and I just copy and paste whatever I want whether it's full structure or in my case I would copy and paste so response should be data and then this result comma is not needed of course not formatted but I click comment out L in phpstorm means code reformat or it will be menu item code reformat code and that code doesn't need to be spaced or tabbed correctly here in the documentation that is perfectly fine then we run API dog generate and let's refresh our documentation this and let's go to categories and there we go it's formatted automatically so this is the updated documentation for that API call so these are the basics how to generate simple API documentation for more complex documentation may be may be it's worth checking out open API standard or former called swagger it's a more standard approach across the API world not only laravel and we have a separate article on that one quick admin panel blog with a demo about open API swagger and documentation looks a little bit different but in here it's much more work to generate the API many more parameters and stuff to write like this so I would suggest open API for more complex projects but for simple API is Marcel's package laravel API job generator is a perfect tool that's it about API Docs for this time and see you guys in other videos

Channel: Laravel Daily

Views: 58,648

Keywords:

Id: zky95P5ytic

Length: 6min 27sec (387 seconds)

Published: Thu Mar 26 2020