#03 API Documentation in Laravel - L5-Swagger and Postman - REST API Development in Laravel

hi welcome to our rest api development part 3. today we're going to make our basic setup for documenting our api and definitely know what's the ipad recommendation and why we need that api documentation so let's start so first thing what is api documentary uh api documentation is something like containing instructions how effectively someone can use and integrate our api to any system means we create api and definitely we use this in our system but people also can use this in their system like we are making an api that can be used in web that can also be used in mobile mobile or app developers can see the documentation and use that on their platform so this is api documentation and why is that api documentation quickly explain what its apis will do and if there is a good api documentation developer does not need to create same api again and again but sometimes if they don't know what's make what's give what's already there if the system is very large then this api recommendation helps a lot if you are working with some individuals or some companies or some partnership then they must have to use your apis right you have to provide them some apis with a good documentation so how many types of api documentation and how will make that api combination uh divides based on their specification like there are three specifications a popular specification out of the internet like open api specification raml specification api blueprint specific uh open api specification is based on json json format or json language and rml is based on yml api blueprint is based on markdown so these are some common way and means we'll write some json code and it will generate an api for us we'll write some yml code and it will generate an api for us we'll write markdown and it will generate an api for us we can use swagger which will use the open apache specification for our documenting our apis also we can use postman to share our apis to developers uh or something like that it's this is very simple let's see the simplest first first you need to install the postman app there is also a chrome extension for that or mozilla add-on for that so you can install that chrome extension or mozilla add-on and after that you can open it from here okay so i'm just downloading this app from mine and after that uh if you open this postman you will see something like this definitely there is nothing in your sidebar i have already worked with some apis that's that's why it's coming in our last tutorial we have uh made an api for our products so copy this url and paste it in this place okay this is postman and look this is a get request right so we are not making post requests we are making get request so you have to select this get in this postman and if you click you can also pass any additional parameters in here like uh also pass here like as for example api key look apk and there is value so you can pass also parameters here and you can pass also some headers authorization and some other stuffs if you want so for now we don't need nothing like this also don't need like this so just hit send and you will see the response in here awesome look there is a proper uh well formatted response is and then one more api like product slash id one it will show also something but we don't actually created that api yet that's why it's empty no problem what if if we just send someone to use this api how we can do that with this postman there is also a way to do that the first you have to create a collection let's create a collection laravel rest api rest if you have created a collection laravel rest api okay so look there is a collection created here that's awesome next whatever url you hit at click on control save or just save it and then you will see the request name you can save it in your in our folder in our collection laravel rest api you can assume this as a folder okay you can create also multiple folder there like uh we we want to work with product this is a apis for products let's create a folder for products push this uh save this here but before saving let's rename it rename it to for get product save to products awesome look there is the api is saved in here awesome and also same for this save this and i will rest api and products name it like single product single product wow so we have two apis in products folder you can also create some other you can also create some folder like add folder like categories or something other stuffs if you want and if you want to create a post request how we can create that uh after the products you just change the method to post so definitely for our uh storing products we will use this post method okay so save this save this as save product or create product so it would reliable rest api and then products save and look there is a post api registered here so we have this now what we can do we there is a way to share this click on collection link and get a link it will uh create a link on get postman server and copy to clipboard and you can actually share this link to your colleagues to your developers everyone so if you just enter it you'll see the a json scheme effort if your postman is open uh open our actual postman chrome extension open you it will be automatically imported there or you can just import import manually from here import and import drag and drop this file then you will see exactly same interface or your developers will see the exactly same interface then it would be very easy to see what's included or not so this is a very simple way we don't actually write this we'll use swagger for our documentation and this uses open api specification and other stuffs this is a very popular platform to documenting our apis so let's do that in laravel there is also a package called l5 swagger we'll install this dark online slash l5 swagger go to that so we need to install this let's click on this installation and configuration we're using laravel 9.2 and php 8.81x so we'll use this to install this composer package let's install this so we'll use this composer require dark online l5 server enter it look we have added this or it will be automatically added and the sagar api is installing under the hood it actually uses jar code swagger php library and some others library swagger ui all other libraries okay so next next would be in config app.php use these uh add this in our provider array config app.php after in after year package service providers placed it here okay so we have registered this provider that's it so we have done so let's see our api uh will be stored here or not we will get this route so if you slash a pay documentation wow look it's coming okay so it's awesome look there is a there is a race api endpoint created for us which uh showing a ui but it's not it's not coming anything yet so don't worry we have uh done our first step and next is in order to generate the swagger api documentation for your api so that offers a set of annotations or to declare and manipulate the output so we have to use that actually so there is also some more configuration let's let's publish the swagger provider publish this provider so after publishing this provider you will see a new file in config folder l5 slash l5 swagger i'll go through this later and then you will click on page partition l5 swagger generate it it will actually generate apis for your look uh here is the ur says this api docs json not found so after installing this piece version l5 swagger generate uh you will see in actually an error because we have not made some more setup for this so let's just do make more setups so what's the mode setup setup is we have to um add some annotations so open epi annotations can be found here click on this link click on this open api annotations can be found here link uh you will see a basic link this link will be must registered in our system and we can add that in the controller http controller and we can add that in this controller in in con base controller or we can use this that in separate make a separate controller and we can add that but for now i am not doing doing those stuffs so okay so if this is actually open ap open fbi info is basic the information of our docs so let's just remove this logo we don't need that and make the title uh like our laravel rest api documentation okay laravel rest paid documentation that's it let's keep the description as it is and it definitely for contact you can name your email i am giving my email so you can give your license or whatever we don't care about license for right now so keep it as it is and after that reload this stores to see if anything changes or not so still we have got this so next step is we will add is demo specification so for click on this pad store example we need actually one route for one route to document the api that's it so go to controllers and this pad dot php and copy a get request this copy this pad copy this line to line number 66 to line number 106. copy this this is actually long no problem go to products controller in products controller on line number remove line number 22 to 26 remove this remove this and paste that documentation okay save it and after that i don't need actually security and security stuff just for now just delete this also the comma and also this json content is not necessary for us just delete this okay successful operation and uh it would be it would be uh the path the path is the hour ap endpoint so it would be products like slash api slash products this is our api endpoint right and text we can make this tag as products and make this method a good name like get all products and operation id operation id is the method name this index so for our case this find by status would be index and deprecated true that means uh this api is deprecated we don't need this for now okay we can delete this letter but let's see after running the command again this version l5 swagger generate it will actually generate a json schema for us let's enter it wow that's awesome so regenerating ap docs default that's awesome so if you see this that means our api generation is done now reload this wow that's super exciting so let's see our um info title and some other stuffs in email separate to license that's it and we have created a text the products tag and before inside that there look there is an api class api slash products if you click this and try now and click execute wow super exciting let's see our apis is response is coming here that's awesome and you can also get some way to do that so we have made our uh api documentation let's improve it little more every time you add something in here it will not automatically add it so to do that what you can do we can actually make alpha l5 swagger generate always to true in dot env file so go to our env file enb and then just make this l5 swagger generate to paste it here always equal true okay what it will do oh so we don't need to generate the apis again and again it will automatically generate and definitely you have to start the password this server for that the f5 server generated awesome and let's change in our apis like products controller so name these tag capital p products get all products for rest api okay we have just changed this text and that now reload this and definitely we must have to start our server this partition serve wow look it's automatically changes we don't need to write manually the generate command every time if we make this way and let's learn a little bit the configuration file so if you go to config l5 swagger you will see the configuration default title uh routes the default uh route endpoint registered this is a pedometer you can change this so that docks json files yml file and some other steps annotations so it will keep the annotation from app folder from this folder if you if you work with another folder so you can append this in here so routes soccer callback and there is also some middleware some other stuffs paths so storage paths api docs this is uh this api json is stored actually in storage slash api docs folder look in this folder storage spot every documentation that's it and there is also a view for that file so i'm not telling yet so this api registered by l5 swagger and they have made a front-end scaffolding for us which is built in react look a i have react extension and it's saying it's actually using the react okay so this front end is done by them we don't actually think about this slot so and and base l5 swagger base path this is not so important scan options uh exclude we can actually exclude a path if we want the that these paths is not necessary to count and whenever we will work with uh authentication then we'll use this security schemes for authenticating our any apis there is also probably it's providing defaults we'll use this so general generate always look this generate always we have given l5 soccer generator overall by default it's false but in env we have give this true so it will be auto generated every day and generate yml copy we don't need that so we keep that as 80s if you want to extend you just copy these variables to env and use at is your own don't change in here it's not recommended okay so there is also a ui so ui is this this is this is our ui and one more important thing is authorization persist authorization it is important for our when we have added our authentication stuff so i would prefer to make this equal true so that if we authenticate once it will store the cookie and we don't have to give the authentication again and again okay so that's it so that's awesome okay so next let's change something in this uh api so that we can understand the sagar a little bit more look there is a parameter already added there parameter is for this whenever we go there this is the parameter look there is a parameter actually status status parameter is added this will be added in query so whenever we try it out let's change this pending execute it if you execute it you will see status equal pending look it has been added in this query so if we make this in query then it will be added in here actually for get route we definitely use this in query so that you can grab that from query data okay so and the description is that that is the description status values for this this is the description and explore we can also make this required or whatever and we can also give some default values like where schema default available and um and we can also give some enamel if you don't give this a name and then it will actually uh make a normal input look we have deleted this anom and if this is now an actual input field we can just give the in input so it depends if you know your statuses then you can make that in nm but for now we don't need this type of parameter we need actually uh like uh let's add a pagination in our apis so get all get there is a get all method and this uh this page in it is 10 so let's make this uh per page per page equal to 10 make this a default value of 10 so and in here no not 10 make this per piece so this is good and definitely in card interface get all we have to add in per page okay so then it would be consistent okay so in product repository so we have added the pagination way here by default it would come 10 so let's pass we can pass the purpose in here so for that we can actually make a request instance here but i am not doing this for index page let's make this from request and then per page okay so request purpose and definitely then we don't need the status name let's make this name purpose and definitely did vary in query required true but we don't make this required true it's not necessary to get this by default it would make 10 default is available no make this default s10 because we have past 10 there and type is string but type is integer make this integer and nm is not necessary for this okay let's save this and reload it here well look it's now awesome like definitely we also have need to change this uh description a bit like okay that's awesome so now if we just execute we don't need to give this it will be automatically executed look that we have seen the two products that's awesome but if we use pagination here like in insert two but but we have already two only two products let's add one so that we can see the pagination working or not wow look this there is only one product and this pagination actually works as it is so two total awesome and here the perfect is added that's it look now we can uh use this great api documentation system in our for more schema types types of like these you can actually read the default uh default this system there is many many more stuffs added in here so you can read this that's awesome we have added api documentation in our system next we will work with authentication uh whenever we will work authentication or any next apis will definitely make that with the help of this api documentation system so if you're still not subscribed on my channel please subscribe and make your comment if you have faced any problem so see you soon bye

Channel: Maniruzzaman-Akash

Views: 9,897

Keywords: laravel rest api, laravel api, api development, rest api, laravel development, laravel 9.x, laravel api development, laravel new video, laravel complete project, laravel swagger, laravel jwt, laravel learnings, laravel, repository pattern laravel, swagger api documentation, interface laravel, laravel advanced feature, laravel api crud, laravel crud, api project, laravel free api development tutorial, laravel migration, laravel installation, api documentation in laravel

Id: PP1vxV0IGVM

Length: 23min 38sec (1418 seconds)

Published: Wed Jul 20 2022