Swagger documentation for php api | Complete crud documentation using swagger [Super easy] 2022

welcome guys welcome to this video so in few videos back we worked on a api using pd pdo and php and the api endpoints are here you can see on the screen so we are going to add this regular documentation so you can see here we have each of the routes if you haven't checked that video this is the video and the link is in the description please check this video before starting on the tutorials because uh in that video we created the complete api and all these endpoints and here in this video we are going to add the documentation to all of these endpoints so if you see here basically we have get throughout we have post wrap put delete if i click any of these we get the option try it out you can click there and hit execute and we get all the data just like we tested in our app so in our app here we have the same route we hit send and we get all the posts the same way we are getting it in our documentation now we are going to see multiple things here we are also going to see how we pass the parameters how we pass the objects how we destroy in for you because in when we are going to get the single record we are going to pass id so those kind of things and we are going to complete the documentation for our api so without further ado let's get started [Music] all right guys to start with i am on the page of download the zip for the api so you need to download this the link is also in the description so the api that we created we have the zip for it so i save it i'm going to extract it extract it here and yeah we have the sky folder here so what i need i just need this folder and i'm going to chain this to test because currently we are going to use the dust test and i'm gonna you can maintain whatever name you like i'm just changing it just to um handling my local host because i already have a small project on sky so here i have test and what i'm going to do currently this is displaying from test so what i'm going to do i'm going to rename it you put something and we're gonna paste it here so we have our test here now and uh if i go here and refresh you can see this is not anymore available so our code is brown here now we need to open it in the code editor drop this to the code editor so here it is now we mainly have i'm gonna have your api so we have the api endpoints here then basically these are the files so if we want to insert something we will be going into test api then post and after that we need to go to this file which is inserted on php so so that's how it works currently it's blind because uh it's not going to work straight away they're going to be some errors you need to correct it we just download it so and then we can config we have database class and where we have our database connections we need to make sure our database is there so we have a database connected here with the name of test it has two tables posts and category can post table has these fields and some data already present there as well as in category we have the category name only and in post table we have category id so the related id from this like for three id here is the id in this table like it refers to this java all right so that's good so far now what we need to do basically we have a models directory and there is a class we have which is post class where we have all these methods those are responsible for reading and selecting and updating data so everything is happening from here so we need to uh put the endpoints to the swagger documentation so for that we go to the swagger api swagger dash ui so if you go to just search simply swagger ui and you follow the link from the tracker io there you will get the option of download trader ui and that will take you to ultimately if you click here it will take you to the same link so here uh we need to download it or we can clone it as well so what i do simply all right so i need to open the directory the htdocs folder where i have this project and localhost test in my terminal so these files will be there so let's go and do that so i open the terminal here and i say cd dash dash dash and then here i say ls so i have my exam here so i can go into it cd samp and then hd docs and there we should have our folder with the name of test so i go inside it simply so i say cd test and then ls so we get the same files you can see here api config model and readme text brilliant now at the same place we want to get this swagger ui so i go here and i simply copy this we are going to clone it so here i'm going to say git clone and put link and then it is going to clone it there now if i go to directory here if we say so you can see we have the swagger ui folder created it's going to take some time because it's downloading right now so we need to wait till it completes now this is complete and if i go back to the folder now we can see there are so many files in here and inside these what i'm going to do we're going to uh i want to show you a website before we proceed so if i go to the browser and search google and all you need to do simply swagger and php when you have this you come to this is our code and dot could have done io just click there and here you will see the documentation how things work you know and we have reference we have user guide you can check here you get the game annotations button notations we need to add we will be adding these annotations in our code very soon so you will see there so this is the site to check if you face any trouble now what we need to do back to the code if i go here uh what we need to do basically inside the api directory now along with the post we're going to uh create another directory it's going to be documentation and here we're going to handle everything so i'm going to call here a file for the name of index.php and that's the file which is going to display us all the documentation of swagger so this is the file so what we need to do here we need to go into sweater dash ui inside here in folder you will see an index.html file we need to copy everything from here and paste everything in here so in the index.php so this is the file we are using now the other thing we need to do is we need to update the path because the files are now because this file going to use css so you can see that the folder is here and we are calling it inside index.php so i'm going to do here i'm going to add here dot dash to go one folder out another and after that we want to pass here swagger ui which is the folder of names so mega dash ui and then we have css so this is where we need to pause i'm going to pause here as well then here same way i'm going to pause it here for the js files so if you get the point basically all we are doing is move one file from there but we won't just ucs and gss css and js from this recognize ui so we are just updating the part there all right so far so good now what we need to do we need to uh create a file because what happens is swagger uses json so whatever functionality we are doing we need to convert it into json so in the model we have post model and here we have this function so we need to put this function in a json file so that swagger can understand it and for doing that if i go here in the swagger dash ui scroll down you will notice here how they suggest we need to do it so okay for the installation i will refer to their uh this is our code and github website here if i go to installation we have option to run composer and install it all right we need to also install this circuit uh swagger php for p command but at the end i'm going to put uh define the version number we're going to 3.2 2.0 and this is the version we want to install so make sure you get the same version now also we need to install one other package here so it's a composer require dot drain annotations so we need this as well so it's gonna and automatically all version you have my composer.json and there it's going to show you the version so we have the exact version we need so both the commands are done and this is all set so what we need to do currently we need to create a file so if i go to the documentation here what they suggest is generate open api documents and when you go inside this document scroll down you will see uh using php we need to use this and what is it exactly that's going to do it it's going to scan a directory where we have our php files and it's going to convert it to json or yaml so we agree to convert in json so we will be changing the code a bit so what we need to do here inside documentation i'm going to create a new file it's going to be api.php i'm going to copy all this code from here and paste in here now here i'm going to say it's going to be json and same here all right and now it is going to do the required style whatever required for our process now the thing is this is only using autoload file this autoload file is present inside vendor folder so if i open this form you will notice here auto load now here it says straight away vendor but it is not next to api so we need to change the directory i'm going to put here this so it's going to go one folder out out of documentation then another folder out of api and then going to go inside of render so you will be able to access it or you can use another approach where we simply say let's say i'm gonna show it here so you can say here dollar underscore server and you can simply pass in this array you can say document underscore root so it's going to get the root directory and then what we want to do we want to give the folder name of this application so we created the directory if you remember we pasted uh here inside htdocs and that's test so we need to pass that here it's going to be test and before that they're going to slash here and then test after that we are going to go into the models so we have a models directory there we have a post uh where we have all these functions that's the reason we need to give that directory here so i'm passing that here and here i don't need x okay so it looks good it's fine so what we need to do we need to check it how it works so all we do we go back to here in our app and refresh we go to uh api documentation and here we need to say api.php all right so we get this currently and it says not found and yeah so it's it's currently going actually if you see here it's trying to create an object here it says open abn version but it also says that there is some issue we don't see okay info not found so it's not getting it so basically if i go back here and go into annotations scroll here you will see here this is this quite a similar thing that we are getting in our alert so that's what we need to fix now so basically we need to add these in our model so that this is going to recognize it so i go back here copy this go to the model and here it can be modeled in the controller wherever your api how you are working with so here on top of this class i'm going to paste this like this all right and here we can tell about our app but that is so i see here pdo php interest api you want to define a version you can define a version as well i say 1.0 so if i go back this time and refresh and you can see that that uh the same error with the info is gone now we have both item and something else going on but uh the first error is gone now let's deal with the other one so for this we're going to work with the read posts function because we want to read the post so if i go to postman let's see if we are getting it we have get we are going to the same url so here we are going to test api post so we can check that here as well so it's going to be post and then after that we have post.php just like that and you can see we get a result here the same way but hit send i'm getting the results here so we are getting the posts right so we want to have in our documentation this route saved and we want to mention that this is getting all the posts so let's do that so here where we have our comment we are going to do here i go back here again i'm going to copy this and i'm going to paste right here all right now here first thing first we need to mention what meta type is let's get our post we have get so it's all right then we need to pause the path here the path is going to be this path so we're just going to copy this so this is the api path where we are getting it now you want to add summary to it posts all right and i'm just going to make it line now we want to put everything inside posts category or tag so we can simply say here tags equals and i'll show you what it what it does but for now i'm just going to add it so i'm going to call it posts all right so this is what it is now if i go back here and refresh we need to go to that api file again so i'm going to copy this and open a new tab and paste here and go back here api slash documentation and documentation and planner so basically we need to make sure we put coma at the end of a statement and then if i go here and refresh we get our json so you can see here open api version then we have info invoice title that we provided but we have the api path we are telling put it under under posts tag where there is summary added here then we have operation id that is generated and then we have response now i want to change it a bit i'm going to copy and paste here another response and i'm going to call it so whatever you put here make sure it is a comment so another spoons i'm going to say here 404 and here it's going to be not found not found another thing i want to add here is the comment that we have on top i'm just going to copy and paste that in our summary so to be and basically so we don't provide any comment here it's just going to be here by default so if i go back here refresh i'll stay the same you know somebody updated now we have one more response here and uh now if you want to see uh what we do we simply go to uh documentation directory of this i copy this go here and paste this here now what exactly i'm doing here is because if you go to any directory and there is index.php there that's going to display so here currently index.php is working and if you remember we have the swagger code given inside it so here we need to do is inspect console and if you notice here we have adder that means the directory is not cracked and we are not loading our js properly all right guys let's correct this header here so we need to check and if i swagger.ui to this and then we have index.html and that's the code we using here so all the js files and css file files are here in this folder so we need to mention it after swagger dash ui so here we say simply test like this and put it here as well same way we need to add it in our css file links so here then here and then here so it goes swagger ui then this folder you put this right yeah and then the files so it should be fine refresh and we have it so you can see here we have uh now great by default it is loading a link that is mentioned in the code so if you go here it says https pet store or swagger and then that is loading so we need to modify this to make it work with our code so we have here uh our code like this so we are passing the json here so just going to copy this link go in here maybe it's going to be http not https and rest we're going to paste like this now it is going to load from this file so if we go back here and refresh okay it's taking htv twice so sorry about that i added it here and refresh okay great so we have the posts here and we are getting this get route so if i click here you can see here method to read all so what a summary we provided here uh that is showing up in uh detail we are not using any parameter in this one but the url is in the get request if you want to check you can click try it out execute and you can see the results it's showing just like postman the other spot showing up here now let's add it to the other methods so if i go back here in the post now the second method are is that getting a single post so for that simply what i'm going to do first of all i'm going to copy and paste these and paste here just like that and then method i'm going to cut this uh comment to the summary all right then we have the url so for reading the url remember in our api we are using single and then we are passing the id so we need to do something similar here so the file going to be single dot php and here we have the tags post if i go back here and refresh you will see we have here so what tags does if i say here let's say let's simply remove this line so if i remove the tag and go back and refresh you will see it goes in default so we have posts and routes here and default here so if you want to have a separate category you can add it like that so i have everything inside posts as its post model we are working on so i'm passing this great methods response responses going to be these two and i'm not going to change there but we need to pass an id here so that we can read so that's going to be a parameter type so for passing parameter what we do we simply say here uh at o a and after that slash capital p and we say para meter and then we start here like this and put coma for sure and after that inside it what we want to do we want to define all the parameters so here just i'm going to say here name is equal to going to be the id so we want an id and it's going to be in equals query all right and then we want to say required and then now to you what you're going to say here required to uh it is required in our case uh it is true and then at last we want to say uh description [Music] okay so here i'm going to say the passed to get query string to get the data like in query string so like in the pause and string we're passing here just the same way again put a comma after that what we want to do we want to mention the schema for that at oa capital and then we say here schema capless and schema and after that brackets and then here inside it we are going to mention the schema so it's going to be type and we want to say it's a string okay so so far so good let's see if it works go back there refresh uh we don't have any uh if you uh face any adder in here uh most probably you will see enter here otherwise your route will be disappeared from here so now if i go here we have option of id and string type and we need to pause it so you can see in the id pass to get data like your restraint the description that we added here it's showing up there so that's helpful now when you can try it out you need to pass an id so if i go to postman we have the posts with id 10 here so i can pass id10 and execute so scroll down we have this detail coming up so it's a success so if i go to postman uh the same details are here you can see all right so we have successfully added the round for our documentation with the parameter type it's great now let's work for further here uh we need to get here another method which is to create a new post so uh it's going to be a bit different because it's going to be type post so i'm going to copy the whole code and we will change it so paste here and obviously common goes to summary again all right now method is going to be post [Music] and here file going to be insert now yeah tag we want the same categories it's going to be there just the same way parameter i'm going to change this portion because this time we want to pass values so if i go here in postman and go in insert query so here when we insert we pass the data using form data so or in the application we are expecting using post so we need to change it it's not going to get from here so to pass the post values what we do we do something like this so here we are going to say it's going to be at oa response [Music] and it's a response sorry requested this request by [Music] and then make sure it is like that then here head over and then it is going to be media type again parenthesis here and we want to add more data inside inside it first thing first we want to pause here is the media type so you're telling what type of media we are passing and this is going to be multi-part form data because we're passing we're expecting value values from post so that's going to be from form so add and the schema we need to define get less schema in here we're going to pass the wellies all right so values we want to pass here it's like that op and each value going to be called property and in each property we will define the type and name so let's do that so here you want to say okay it's going to be property and which is going to be type title sorry it is the name of it so the field name is our title and then type a string okay we have few properties here so for inserting um so when we go here and we get it so we have few fields here and we are getting category name but in the database we when we insert data we have category id so we need to pass that away so i'm going to simply copy this and i'm going to align it [Music] all right the same way come again paste again and like that so in database we are expecting title category id description so all these three we need second going to be description and then give the category [Music] underscore id this is going to be type integer and string and string that's fine all right all good so it looks fine to me let's test it so it works so go here refresh okay something is not right okay we need to pass commas make sure you pass commas other than that uh request body media type media type let's refresh okay great all set we have another one here uh the insert drive this time now when i open this we have the title description categories if i you can see here i'll type here from data so try out so we say here let's say title sum title to test swagger all right some description to test swagger and category that's a two and then i execute it and we get post added successfully so this response that we get that get because the in the creation we are saying true and when it inserts we're returning that and when we're turning it and that's happening inside if we go to api post and for insert here scroll down we have here post added successfully so from here it is coming so that's why it says here hosted successfully so if i go to database and see here you can see that we just got a new record which is from the swagger documentation and that's great so you can have documentation you can have all the details about it what feeders are there what fields types are there what is the purpose of this and again you can test it as well brilliant so we have three routes here let's add another two so let's go to the post model here if i go and now we need to work on update so update is going to be quite similar to the create so i'm just gonna copy the create and i'm gonna paste here all right so these and i take the comment put in summary so you can put anything you will like so that makes some sense to your application file name this time it's going to be update now for understanding these routes please check the previous video where we created this api otherwise you will be lost so here we have put tag is going to be post posts now here request body we need to add one more thing because we are going to update a particular post so we are going to do it by the id because if you see in the code we have passing programs we have id here and then we are saying where id is this update particular post so we need to pass id so all we need to do is another property and if you guessed it why is that probably going to be the id so it's going to be id here it's going to be integer let's test it out so go here refresh we have put requests method for updating posts yeah here we have all the fields given and try it out so now i'll go to the postman here and go to all posts so here if you see we have a post with the id 10 and this is the detail so i want to change it so let's say it goes with the id10 and updated using swagger uh updated using swagger description and category category.101 all right now execute and we have another let's see why is that so it didn't give us the response that we are expecting so back to code okay so uh for this we are going to change the media type for updating we're going to change it to json and uh here if i go back and refresh and this time you will see that it's changed to json and we have a json object here so try out id the same 10 and i'm gonna pause here uh updating using and category id1 execute it and we get post updates successfully now if i go to here and send again and with the id of 10 you can see updating a bit using swagger so it operated it okay so if i go to the code here in update uh here we are getting the values go to update.php so this is done using object here you can see so we are getting the value and then converting it into params and then passing it that's the reason when i was trying to insert using form data we got issue and uh in the code we had to change it to json so that's important because if you go to the create method and we use the form data there so for create we have inserted on php and there we are using you can see here post so if you if data comes from post so we both using both here actually we have for object here and for post here so if it is post it is going to do this code if it is object it's going to do this and for our update we only have for json so that's the reason we needed to change that there okay so far so good so far we have our four rounds and update is working as well so early now let's add the last one which is the delete so here here's the method now delete is going to be quite simple so what i do we take from every single this one so scroll down and paste here changing the description with the our comment all right and here it's gonna be destroy because the file name is just right here now method post and we need to pause here uh now let's see what we expecting there so if i go to destroy.php here we are again expecting the json here so let's deal with that here we are passing parameter and we need to pause body type actually so i'm going to copy this from here i'm going to paste here okay now here all we need to do uh we need to pass the id nothing else so we have the id we are passing it there if i go back here refresh okay we have it here but we need to change this method to delete okay refresh we have delete now let's see if it works so we need to pause object and json we added it there now let's delete 10 so execute post deleted successfully so if i go to postman hit it again you can see the post with the id of 10 is not there so even you don't need to go to postman you can simply go above here because you have the first getting all the posts try it out execute and you will see that there is no post with id10 it's deleted so let's delete this seventh one as well so i'm gonna go here and i say reset pause here id seven execute post deleted let's go here cancel try it out execute and you can see that sound is gone as well all right so you can see that we created an api now we have all the endpoints of that api we have all the details what these endpoints are about we can check we can pass parameters we can pause objects and we are successfully holding it we can have this documentation in our application so you can have it there because your application is here you just created a documentation directory and further your documentation goes so you can access it anyway as you like you can have multiple if you want just create another tag and it's going to work straight away hope you like this this was it for today and i'll see in the next video thank you for watching [Music]

Channel: Zarx Biz

Views: 16,119

Keywords: swagger, php, api, php rest api, json api, json header, php tutorial, learn php, php for beginners, php rest, php oop, php pdo, php restful api, rest api tutorial, rest api, php rest api tutorial, PHP, MySQL, HTML, CSS, PHP CRUD, PHP REST API, REST API, RESTful, How-to (Website Category), PL-PHP, response, error code, headers, programming, swagger ui, swagger ui tutorial, swagger streamer, php pdo swagger, swagger ui api docs, api documentation, api documentation using swagger

Id: J6ZKwg8K--s

Length: 37min 18sec (2238 seconds)

Published: Sun Feb 27 2022